diff --git a/bin/api-docs/update-api-docs.js b/bin/api-docs/update-api-docs.js index 3ee55ff0c3d81..3fc1e6da297e0 100755 --- a/bin/api-docs/update-api-docs.js +++ b/bin/api-docs/update-api-docs.js @@ -38,10 +38,7 @@ const PACKAGES_DIR = resolve( ROOT_DIR, 'packages' ); * * @type {string} */ -const DATA_DOCS_DIR = resolve( - ROOT_DIR, - 'docs/designers-developers/developers/data' -); +const DATA_DOCS_DIR = resolve( ROOT_DIR, 'docs/reference-guides/data' ); /** * Pattern matching start token of a README file. @@ -235,6 +232,9 @@ glob.stream( [ { shell: true } ); } + await execa( 'npm', [ 'run', 'format', output ], { + shell: true, + } ); } catch ( error ) { console.error( error ); process.exit( 1 ); diff --git a/docs/how-to-guides/widgets/legacy-widget-block.md b/docs/how-to-guides/widgets/legacy-widget-block.md index 21d22561d1509..09adca8d1ffda 100644 --- a/docs/how-to-guides/widgets/legacy-widget-block.md +++ b/docs/how-to-guides/widgets/legacy-widget-block.md @@ -89,10 +89,10 @@ This is done by adding JavaScript code to your block's definition. In this examp ```js transforms: { - from: [ - { - type: 'block', - blocks: [ 'core/legacy-widget' ], + from: [ + { + type: 'block', + blocks: [ 'core/legacy-widget' ], isMatch: ( { idBase, instance } ) => { if ( ! instance?.raw ) { // Can't transform if raw instance is not shown in REST API. @@ -100,13 +100,13 @@ transforms: { } return idBase === 'example_widget'; }, - transform: ( { instance } ) => { - return createBlock( 'example/block', { + transform: ( { instance } ) => { + return createBlock( 'example/block', { name: instance.raw.name, - } ); - }, - }, - ] + } ); + }, + }, + ] }, ``` diff --git a/docs/reference-guides/data/data-core-annotations.md b/docs/reference-guides/data/data-core-annotations.md index 7b347df85a7f5..f1d1d6918e5c5 100644 --- a/docs/reference-guides/data/data-core-annotations.md +++ b/docs/reference-guides/data/data-core-annotations.md @@ -4,16 +4,16 @@ Namespace: `core/annotations`. ## Selectors - + Nothing to document. - + ## Actions - + Nothing to document. - + diff --git a/docs/reference-guides/data/data-core-block-editor.md b/docs/reference-guides/data/data-core-block-editor.md index 97011bcce9105..66a836475d42d 100644 --- a/docs/reference-guides/data/data-core-block-editor.md +++ b/docs/reference-guides/data/data-core-block-editor.md @@ -4,9 +4,9 @@ Namespace: `core/block-editor`. ## Selectors - + -# **areInnerBlocksControlled** +### areInnerBlocksControlled Checks if a given block has controlled inner blocks. @@ -19,7 +19,7 @@ _Returns_ - `boolean`: True if the block has controlled inner blocks. -# **canInsertBlocks** +### canInsertBlocks Determines if the given blocks are allowed to be inserted into the block list. @@ -34,7 +34,7 @@ _Returns_ - `boolean`: Whether the given blocks are allowed to be inserted. -# **canInsertBlockType** +### canInsertBlockType Determines if the given block type is allowed to be inserted into the block list. @@ -48,7 +48,7 @@ _Returns_ - `boolean`: Whether the given block type is allowed to be inserted. -# **didAutomaticChange** +### didAutomaticChange Returns true if the last change was an automatic change, false otherwise. @@ -60,7 +60,7 @@ _Returns_ - `boolean`: Whether the last change was automatic. -# **getAdjacentBlockClientId** +### getAdjacentBlockClientId Returns the client ID of the block adjacent one at the given reference startClientId and modifier directionality. Defaults start startClientId to @@ -77,7 +77,7 @@ _Returns_ - `?string`: Return the client ID of the block, or null if none exists. -# **getBlock** +### 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 @@ -103,7 +103,7 @@ _Returns_ - `Object`: Parsed block object. -# **getBlockAttributes** +### getBlockAttributes Returns a block's attributes given its client ID, or null if no block exists with the client ID. @@ -117,7 +117,7 @@ _Returns_ - `Object?`: Block attributes. -# **getBlockCount** +### getBlockCount Returns the number of blocks currently present in the post. @@ -130,7 +130,7 @@ _Returns_ - `number`: Number of blocks in the post. -# **getBlockHierarchyRootClientId** +### getBlockHierarchyRootClientId 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. @@ -143,7 +143,7 @@ _Returns_ - `string`: Root client ID -# **getBlockIndex** +### getBlockIndex 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. @@ -158,7 +158,7 @@ _Returns_ - `number`: Index at which block exists in order. -# **getBlockInsertionPoint** +### getBlockInsertionPoint Returns the insertion point, the index at which the new inserted block would be placed. Defaults to the last index. @@ -171,7 +171,7 @@ _Returns_ - `Object`: Insertion point object with `rootClientId`, `index`. -# **getBlockListSettings** +### getBlockListSettings Returns the Block List settings of a block, if any exist. @@ -184,7 +184,7 @@ _Returns_ - `?Object`: Block settings of the block if set. -# **getBlockMode** +### getBlockMode Returns the block's editing mode, defaulting to "visual" if not explicitly assigned. @@ -198,7 +198,7 @@ _Returns_ - `Object`: Block editing mode. -# **getBlockName** +### getBlockName Returns a block's name given its client ID, or null if no block exists with the client ID. @@ -212,7 +212,7 @@ _Returns_ - `string`: Block name. -# **getBlockOrder** +### getBlockOrder 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 @@ -227,7 +227,7 @@ _Returns_ - `Array`: Ordered client IDs of editor blocks. -# **getBlockParents** +### getBlockParents Given a block client ID, returns the list of all its parents from top to bottom. @@ -241,7 +241,7 @@ _Returns_ - `Array`: ClientIDs of the parent blocks. -# **getBlockParentsByBlockName** +### getBlockParentsByBlockName Given a block client ID and a block name, returns the list of all its parents from top to bottom, filtered by the given name(s). For example, if passed @@ -260,7 +260,7 @@ _Returns_ - `Array`: ClientIDs of the parent blocks. -# **getBlockRootClientId** +### getBlockRootClientId 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 @@ -275,7 +275,7 @@ _Returns_ - `?string`: Root client ID, if exists -# **getBlocks** +### getBlocks Returns all block objects for the current post being edited as an array in the order they appear in the post. Note that this will exclude child blocks @@ -296,7 +296,7 @@ _Returns_ - `Object[]`: Post blocks. -# **getBlocksByClientId** +### getBlocksByClientId Given an array of block client IDs, returns the corresponding array of block objects. @@ -310,7 +310,7 @@ _Returns_ - `WPBlock[]`: Block objects. -# **getBlockSelectionEnd** +### getBlockSelectionEnd Returns the current block selection end. This value may be null, and it may represent either a singular block selection or multi-selection end. @@ -324,7 +324,7 @@ _Returns_ - `?string`: Client ID of block selection end. -# **getBlockSelectionStart** +### getBlockSelectionStart Returns the current block selection start. This value may be null, and it may represent either a singular block selection or multi-selection start. @@ -338,7 +338,7 @@ _Returns_ - `?string`: Client ID of block selection start. -# **getBlockTransformItems** +### getBlockTransformItems Determines the items that appear in the available block transforms list. @@ -372,7 +372,7 @@ _Properties_ - _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item. - _frecency_ `number`: Heuristic that combines frequency and recency. -# **getClientIdsOfDescendants** +### getClientIdsOfDescendants Returns an array containing the clientIds of all descendants of the blocks given. @@ -386,7 +386,7 @@ _Returns_ - `Array`: ids of descendants. -# **getClientIdsWithDescendants** +### getClientIdsWithDescendants Returns an array containing the clientIds of the top-level blocks and their descendants of any depth (for nested blocks). @@ -399,7 +399,7 @@ _Returns_ - `Array`: ids of top-level and descendant blocks. -# **getDraggedBlockClientIds** +### getDraggedBlockClientIds Returns the client ids of any blocks being directly dragged. @@ -413,7 +413,7 @@ _Returns_ - `string[]`: Array of dragged block client ids. -# **getFirstMultiSelectedBlockClientId** +### getFirstMultiSelectedBlockClientId Returns the client ID of the first block in the multi-selection set, or null if there is no multi-selection. @@ -426,7 +426,7 @@ _Returns_ - `?string`: First block client ID in the multi-selection set. -# **getGlobalBlockCount** +### getGlobalBlockCount 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. @@ -440,7 +440,7 @@ _Returns_ - `number`: Number of blocks in the post, or number of blocks with name equal to blockName. -# **getInserterItems** +### getInserterItems 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). @@ -478,7 +478,7 @@ _Properties_ - _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item. - _frecency_ `number`: Heuristic that combines frequency and recency. -# **getLastMultiSelectedBlockClientId** +### getLastMultiSelectedBlockClientId Returns the client ID of the last block in the multi-selection set, or null if there is no multi-selection. @@ -491,7 +491,7 @@ _Returns_ - `?string`: Last block client ID in the multi-selection set. -# **getLowestCommonAncestorWithSelectedBlock** +### getLowestCommonAncestorWithSelectedBlock Given a block client ID, returns the lowest common ancestor with selected client ID. @@ -504,7 +504,7 @@ _Returns_ - `string`: Common ancestor client ID or undefined -# **getMultiSelectedBlockClientIds** +### getMultiSelectedBlockClientIds Returns the current multi-selection set of block client IDs, or an empty array if there is no multi-selection. @@ -517,7 +517,7 @@ _Returns_ - `Array`: Multi-selected block client IDs. -# **getMultiSelectedBlocks** +### getMultiSelectedBlocks Returns the current multi-selection set of blocks, or an empty array if there is no multi-selection. @@ -530,7 +530,7 @@ _Returns_ - `Array`: Multi-selected block objects. -# **getMultiSelectedBlocksEndClientId** +### getMultiSelectedBlocksEndClientId Returns the client ID of the block which ends the multi-selection set, or null if there is no multi-selection. @@ -549,7 +549,7 @@ _Returns_ - `?string`: Client ID of block ending multi-selection. -# **getMultiSelectedBlocksStartClientId** +### getMultiSelectedBlocksStartClientId Returns the client ID of the block which begins the multi-selection set, or null if there is no multi-selection. @@ -568,7 +568,7 @@ _Returns_ - `?string`: Client ID of block beginning multi-selection. -# **getNextBlockClientId** +### getNextBlockClientId 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 @@ -583,7 +583,7 @@ _Returns_ - `?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 @@ -598,7 +598,7 @@ _Returns_ - `?string`: Adjacent block's client ID, or null if none exists. -# **getSelectedBlock** +### getSelectedBlock Returns the currently selected block, or null if there is no selected block. @@ -610,7 +610,7 @@ _Returns_ - `?Object`: Selected block. -# **getSelectedBlockClientId** +### getSelectedBlockClientId Returns the currently selected block client ID, or null if there is no selected block. @@ -623,7 +623,7 @@ _Returns_ - `?string`: Selected block client ID. -# **getSelectedBlockClientIds** +### getSelectedBlockClientIds Returns the current selection set of block client IDs (multiselection or single selection). @@ -635,7 +635,7 @@ _Returns_ - `Array`: Multi-selected block client IDs. -# **getSelectedBlockCount** +### getSelectedBlockCount Returns the number of blocks currently selected in the post. @@ -647,7 +647,7 @@ _Returns_ - `number`: Number of blocks selected in the post. -# **getSelectedBlocksInitialCaretPosition** +### getSelectedBlocksInitialCaretPosition Returns the initial caret position for the selected block. This position is to used to position the caret properly when the selected block changes. @@ -661,7 +661,7 @@ _Returns_ - `0|-1|null`: Initial position. -# **getSelectionEnd** +### getSelectionEnd Returns the current selection end block client ID, attribute key and text offset. @@ -674,7 +674,7 @@ _Returns_ - `WPBlockSelection`: Selection end information. -# **getSelectionStart** +### getSelectionStart Returns the current selection start block client ID, attribute key and text offset. @@ -687,7 +687,7 @@ _Returns_ - `WPBlockSelection`: Selection start information. -# **getSettings** +### getSettings Returns the editor settings. @@ -699,7 +699,7 @@ _Returns_ - `Object`: The editor settings object. -# **getTemplate** +### getTemplate Returns the defined block template @@ -711,7 +711,7 @@ _Returns_ - `?Array`: Block Template -# **getTemplateLock** +### getTemplateLock Returns the defined block template lock. Optionally accepts a root block client ID as context, otherwise defaulting to the global context. @@ -725,7 +725,7 @@ _Returns_ - `?string`: Block Template Lock -# **hasBlockMovingClientId** +### hasBlockMovingClientId Returns whether block moving mode is enabled. @@ -737,7 +737,7 @@ _Returns_ - `string`: Client Id of moving block. -# **hasInserterItems** +### hasInserterItems Determines whether there are items to show in the inserter. @@ -750,7 +750,7 @@ _Returns_ - `boolean`: Items that appear in inserter. -# **hasMultiSelection** +### hasMultiSelection Returns true if a multi-selection has been made, or false otherwise. @@ -762,7 +762,7 @@ _Returns_ - `boolean`: Whether multi-selection has been made. -# **hasSelectedBlock** +### hasSelectedBlock Returns true if there is a single selected block, or false otherwise. @@ -774,7 +774,7 @@ _Returns_ - `boolean`: Whether a single block is selected. -# **hasSelectedInnerBlock** +### hasSelectedInnerBlock Returns true if one of the block's inner blocks is selected. @@ -788,7 +788,7 @@ _Returns_ - `boolean`: Whether the block as an inner block selected -# **isAncestorBeingDragged** +### isAncestorBeingDragged Returns whether a parent/ancestor of the block is being dragged. @@ -801,7 +801,7 @@ _Returns_ - `boolean`: Whether the block's ancestor is being dragged. -# **isAncestorMultiSelected** +### isAncestorMultiSelected Returns true if an ancestor of the block is multi-selected, or false otherwise. @@ -815,7 +815,7 @@ _Returns_ - `boolean`: Whether an ancestor of the block is in multi-selection set. -# **isBlockBeingDragged** +### isBlockBeingDragged Returns whether the block is being dragged. @@ -832,7 +832,7 @@ _Returns_ - `boolean`: Whether the block is being dragged. -# **isBlockHighlighted** +### isBlockHighlighted Returns true if the current highlighted block matches the block clientId. @@ -845,7 +845,7 @@ _Returns_ - `boolean`: Whether the block is currently highlighted. -# **isBlockInsertionPointVisible** +### isBlockInsertionPointVisible Returns true if we should show the block insertion point. @@ -857,7 +857,7 @@ _Returns_ - `?boolean`: Whether the insertion point is visible or not. -# **isBlockMultiSelected** +### isBlockMultiSelected Returns true if the client ID occurs within the block multi-selection, or false otherwise. @@ -871,7 +871,7 @@ _Returns_ - `boolean`: Whether block is in multi-selection set. -# **isBlockSelected** +### isBlockSelected Returns true if the block corresponding to the specified client ID is currently selected and no multi-selection exists, or false otherwise. @@ -885,7 +885,7 @@ _Returns_ - `boolean`: Whether block is selected and multi-selection exists. -# **isBlockValid** +### isBlockValid Returns whether a block is valid or not. @@ -898,7 +898,7 @@ _Returns_ - `boolean`: Is Valid. -# **isBlockWithinSelection** +### isBlockWithinSelection 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" @@ -914,7 +914,7 @@ _Returns_ - `boolean`: Whether block is selected and not the last in the selection. -# **isCaretWithinFormattedText** +### isCaretWithinFormattedText Returns true if the caret is within formatted text, or false otherwise. @@ -926,7 +926,7 @@ _Returns_ - `boolean`: Whether the caret is within formatted text. -# **isDraggingBlocks** +### isDraggingBlocks Returns true if the user is dragging blocks, or false otherwise. @@ -938,7 +938,7 @@ _Returns_ - `boolean`: Whether user is dragging blocks. -# **isFirstMultiSelectedBlock** +### isFirstMultiSelectedBlock 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 @@ -953,7 +953,7 @@ _Returns_ - `boolean`: Whether block is first in multi-selection. -# **isLastBlockChangePersistent** +### isLastBlockChangePersistent Returns true if the most recent block change is be considered persistent, or false otherwise. A persistent change is one committed by BlockEditorProvider @@ -967,7 +967,7 @@ _Returns_ - `boolean`: Whether the most recent block change was persistent. -# **isMultiSelecting** +### isMultiSelecting 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 @@ -985,7 +985,7 @@ _Returns_ - `boolean`: True if multi-selecting, false if not. -# **isNavigationMode** +### isNavigationMode Returns whether the navigation mode is enabled. @@ -997,7 +997,7 @@ _Returns_ - `boolean`: Is navigation mode enabled. -# **isSelectionEnabled** +### isSelectionEnabled Selector that returns if multi-selection is enabled or not. @@ -1009,7 +1009,7 @@ _Returns_ - `boolean`: True if it should be possible to multi-select blocks, false if multi-selection is disabled. -# **isTyping** +### isTyping Returns true if the user is typing, or false otherwise. @@ -1021,7 +1021,7 @@ _Returns_ - `boolean`: Whether user is typing. -# **isValidTemplate** +### isValidTemplate Returns whether the blocks matches the template or not. @@ -1033,13 +1033,27 @@ _Returns_ - `?boolean`: Whether the template is valid or not. - +### wasBlockJustInserted + +Tells if the block with the passed clientId was just inserted. + +_Parameters_ + +- _state_ `Object`: Global application state. +- _clientId_ `Object`: Client Id of the block. +- _source_ `?string`: Optional insertion source of the block. + +_Returns_ + +- `boolean`: True if the block matches the last block inserted from the specified source. + + ## Actions - + -# **clearSelectedBlock** +### clearSelectedBlock Returns an action object used in signalling that the block selection is cleared. @@ -1047,7 +1061,7 @@ _Returns_ - `Object`: Action object. -# **duplicateBlocks** +### duplicateBlocks Generator that triggers an action used to duplicate a list of blocks. @@ -1056,7 +1070,7 @@ _Parameters_ - _clientIds_ `string[]`: - _updateSelection_ `boolean`: -# **enterFormattedText** +### enterFormattedText Returns an action object used in signalling that the caret has entered formatted text. @@ -1064,7 +1078,7 @@ _Returns_ - `Object`: Action object. -# **exitFormattedText** +### exitFormattedText Returns an action object used in signalling that the user caret has exited formatted text. @@ -1072,7 +1086,7 @@ _Returns_ - `Object`: Action object. -# **flashBlock** +### flashBlock Yields action objects used in signalling that the block corresponding to the given clientId should appear to "flash" by rhythmically highlighting it. @@ -1081,7 +1095,7 @@ _Parameters_ - _clientId_ `string`: Target block client ID. -# **hideInsertionPoint** +### hideInsertionPoint Returns an action object hiding the insertion point. @@ -1089,7 +1103,7 @@ _Returns_ - `Object`: Action object. -# **insertAfterBlock** +### insertAfterBlock Generator used to insert an empty block before a given block. @@ -1097,7 +1111,7 @@ _Parameters_ - _clientId_ `string`: -# **insertBeforeBlock** +### insertBeforeBlock Generator used to insert an empty block after a given block. @@ -1105,7 +1119,7 @@ _Parameters_ - _clientId_ `string`: -# **insertBlock** +### insertBlock Returns an action object used in signalling that a single block should be inserted, optionally at a specific index respective a root block list. @@ -1116,12 +1130,13 @@ _Parameters_ - _index_ `?number`: Index at which block should be inserted. - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _meta_ `?Object`: Optional Meta values to be passed to the action object. _Returns_ - `Object`: Action object. -# **insertBlocks** +### insertBlocks 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. @@ -1139,7 +1154,7 @@ _Returns_ - `Object`: Action object. -# **insertDefaultBlock** +### insertDefaultBlock Returns an action object used in signalling that a new block of the default type should be added to the block list. @@ -1154,7 +1169,7 @@ _Returns_ - `Object`: Action object -# **mergeBlocks** +### mergeBlocks Returns an action object used in signalling that two blocks should be merged @@ -1163,11 +1178,11 @@ _Parameters_ - _firstBlockClientId_ `string`: Client ID of the first block to merge. - _secondBlockClientId_ `string`: Client ID of the second block to merge. -# **moveBlocksDown** +### moveBlocksDown Undocumented declaration. -# **moveBlocksToPosition** +### moveBlocksToPosition Returns an action object signalling that the given blocks should be moved to a new position. @@ -1179,11 +1194,11 @@ _Parameters_ - _toRootClientId_ `?string`: Root client ID destination. - _index_ `number`: The index to move the blocks to. -# **moveBlocksUp** +### moveBlocksUp Undocumented declaration. -# **moveBlockToPosition** +### moveBlockToPosition Returns an action object signalling that the given block should be moved to a new position. @@ -1195,7 +1210,7 @@ _Parameters_ - _toRootClientId_ `?string`: Root client ID destination. - _index_ `number`: The index to move the block to. -# **multiSelect** +### multiSelect Returns an action object used in signalling that block multi-selection changed. @@ -1204,7 +1219,7 @@ _Parameters_ - _start_ `string`: First block of the multi selection. - _end_ `string`: Last block of the multiselection. -# **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 @@ -1218,7 +1233,7 @@ _Returns_ - `Object`: Action object. -# **removeBlock** +### removeBlock Returns an action object used in signalling that the block with the specified client ID is to be removed. @@ -1232,7 +1247,7 @@ _Returns_ - `Object`: Action object. -# **removeBlocks** +### removeBlocks Yields action objects used in signalling that the blocks corresponding to the set of specified client IDs are to be removed. @@ -1242,7 +1257,7 @@ _Parameters_ - _clientIds_ `string|string[]`: Client IDs of blocks to remove. - _selectPrevious_ `boolean`: True if the previous block should be selected when a block is removed. -# **replaceBlock** +### replaceBlock Returns an action object signalling that a single block should be replaced with one or more replacement blocks. @@ -1256,7 +1271,7 @@ _Returns_ - `Object`: Action object. -# **replaceBlocks** +### replaceBlocks Returns an action object signalling that a blocks should be replaced with one or more replacement blocks. @@ -1269,7 +1284,7 @@ _Parameters_ - _initialPosition_ `0|-1|null`: Index of caret after in the selected block after the operation. - _meta_ `?Object`: Optional Meta values to be passed to the action object. -# **replaceInnerBlocks** +### replaceInnerBlocks Returns an action object used in signalling that the inner blocks with the specified client ID should be replaced. @@ -1285,7 +1300,7 @@ _Returns_ - `Object`: Action object. -# **resetBlocks** +### resetBlocks Returns an action object used in signalling that blocks state should be reset to the specified array of blocks, taking precedence over any other @@ -1295,7 +1310,7 @@ _Parameters_ - _blocks_ `Array`: Array of blocks. -# **resetSelection** +### resetSelection Returns an action object used in signalling that selection state should be reset to the specified selection. @@ -1310,7 +1325,7 @@ _Returns_ - `Object`: Action object. -# **selectBlock** +### selectBlock Returns an action object used in signalling that the block with the specified client ID has been selected, optionally accepting a position @@ -1326,7 +1341,7 @@ _Returns_ - `Object`: Action object. -# **selectionChange** +### selectionChange Returns an action object used in signalling that the user caret has changed position. @@ -1342,7 +1357,7 @@ _Returns_ - `Object`: Action object. -# **selectNextBlock** +### selectNextBlock Yields action objects used in signalling that the block following the given clientId should be selected. @@ -1351,7 +1366,7 @@ _Parameters_ - _clientId_ `string`: Block client ID. -# **selectPreviousBlock** +### selectPreviousBlock Yields action objects used in signalling that the block preceding the given clientId should be selected. @@ -1360,7 +1375,7 @@ _Parameters_ - _clientId_ `string`: Block client ID. -# **setBlockMovingClientId** +### setBlockMovingClientId Generator that triggers an action used to enable or disable the block moving mode. @@ -1368,7 +1383,7 @@ _Parameters_ - _hasBlockMovingClientId_ `string|null`: Enable/Disable block moving mode. -# **setHasControlledInnerBlocks** +### setHasControlledInnerBlocks Returns an action object that sets whether the block has controlled innerblocks. @@ -1377,7 +1392,7 @@ _Parameters_ - _clientId_ `string`: The block's clientId. - _hasControlledInnerBlocks_ `boolean`: True if the block's inner blocks are controlled. -# **setNavigationMode** +### setNavigationMode Generators that triggers an action used to enable or disable the navigation mode. @@ -1385,7 +1400,7 @@ _Parameters_ - _isNavigationMode_ `string`: Enable/Disable navigation mode. -# **setTemplateValidity** +### setTemplateValidity Returns an action object resetting the template validity. @@ -1397,7 +1412,7 @@ _Returns_ - `Object`: Action object. -# **showInsertionPoint** +### showInsertionPoint Returns an action object used in signalling that the insertion point should be shown. @@ -1406,12 +1421,13 @@ _Parameters_ - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _index_ `?number`: Index at which block should be inserted. +- _\_\_unstableOptions_ `Object`: Wether or not to show an inserter button. _Returns_ - `Object`: Action object. -# **startDraggingBlocks** +### startDraggingBlocks Returns an action object used in signalling that the user has begun to drag blocks. @@ -1423,7 +1439,7 @@ _Returns_ - `Object`: Action object. -# **startMultiSelect** +### startMultiSelect Returns an action object used in signalling that a block multi-selection has started. @@ -1431,7 +1447,7 @@ _Returns_ - `Object`: Action object. -# **startTyping** +### startTyping Returns an action object used in signalling that the user has begun to type. @@ -1439,7 +1455,7 @@ _Returns_ - `Object`: Action object. -# **stopDraggingBlocks** +### stopDraggingBlocks Returns an action object used in signalling that the user has stopped dragging blocks. @@ -1447,7 +1463,7 @@ _Returns_ - `Object`: Action object. -# **stopMultiSelect** +### stopMultiSelect Returns an action object used in signalling that block multi-selection stopped. @@ -1455,7 +1471,7 @@ _Returns_ - `Object`: Action object. -# **stopTyping** +### stopTyping Returns an action object used in signalling that the user has stopped typing. @@ -1463,7 +1479,7 @@ _Returns_ - `Object`: Action object. -# **synchronizeTemplate** +### synchronizeTemplate Returns an action object synchronize the template with the list of blocks @@ -1471,7 +1487,7 @@ _Returns_ - `Object`: Action object. -# **toggleBlockHighlight** +### toggleBlockHighlight Returns an action object that toggles the highlighted block state. @@ -1480,7 +1496,7 @@ _Parameters_ - _clientId_ `string`: The block's clientId. - _isHighlighted_ `boolean`: The highlight state. -# **toggleBlockMode** +### toggleBlockMode Returns an action object used to toggle the block editing mode between visual and HTML modes. @@ -1493,7 +1509,7 @@ _Returns_ - `Object`: Action object. -# **toggleSelection** +### toggleSelection Returns an action object that enables or disables block selection. @@ -1505,7 +1521,7 @@ _Returns_ - `Object`: Action object. -# **updateBlock** +### updateBlock Returns an action object used in signalling that the block with the specified client ID has been updated. @@ -1519,7 +1535,7 @@ _Returns_ - `Object`: Action object. -# **updateBlockAttributes** +### updateBlockAttributes Returns an action object used in signalling that the multiple blocks' attributes with the specified client IDs have been updated. @@ -1534,7 +1550,7 @@ _Returns_ - `Object`: Action object. -# **updateBlockListSettings** +### updateBlockListSettings Returns an action object that changes the nested settings of a given block. @@ -1547,7 +1563,7 @@ _Returns_ - `Object`: Action object -# **updateSettings** +### updateSettings Returns an action object used in signalling that the block editor settings have been updated. @@ -1559,7 +1575,7 @@ _Returns_ - `Object`: Action object -# **validateBlocksToTemplate** +### validateBlocksToTemplate Block validity is a function of blocks state (at the point of a reset) and the template setting. As a compromise to its placement @@ -1570,4 +1586,4 @@ _Parameters_ - _blocks_ `Array`: Array of blocks. - + diff --git a/docs/reference-guides/data/data-core-blocks.md b/docs/reference-guides/data/data-core-blocks.md index 64949ca0f7b9e..ed4610bf7884e 100644 --- a/docs/reference-guides/data/data-core-blocks.md +++ b/docs/reference-guides/data/data-core-blocks.md @@ -4,9 +4,33 @@ Namespace: `core/blocks`. ## Selectors - + -# **getBlockStyles** +### getActiveBlockVariation + +Returns the active block variation for a given block based on its attributes. +Variations are determined by their `isActive` property. +Which is either an array of block attribute keys or a function. + +In case of an array of block attribute keys, the `attributes` are compared +to the variation's attributes using strict equality check. + +In case of function type, the function should accept a block's attributes +and the variation's attributes and determines if a variation is active. +A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. + +_Parameters_ + +- _state_ `Object`: Data state. +- _blockName_ `string`: Name of block (example: “core/columns”). +- _attributes_ `Object`: Block attributes used to determine active variation. +- _scope_ `[WPBlockVariationScope]`: Block variation scope name. + +_Returns_ + +- `(WPBlockVariation|undefined)`: Active block variation. + +### getBlockStyles Returns block styles by block name. @@ -19,7 +43,7 @@ _Returns_ - `Array?`: Block Styles. -# **getBlockSupport** +### getBlockSupport Returns the block support value for a feature, if defined. @@ -34,7 +58,7 @@ _Returns_ - `?*`: Block support value -# **getBlockType** +### getBlockType Returns a block type by name. @@ -47,7 +71,7 @@ _Returns_ - `Object?`: Block Type. -# **getBlockTypes** +### getBlockTypes Returns all the available block types. @@ -59,7 +83,7 @@ _Returns_ - `Array`: Block Types. -# **getBlockVariations** +### getBlockVariations Returns block variations by block name. @@ -73,7 +97,7 @@ _Returns_ - `(WPBlockVariation[]|void)`: Block variations. -# **getCategories** +### getCategories Returns all the available categories. @@ -85,7 +109,7 @@ _Returns_ - `WPBlockCategory[]`: Categories list. -# **getChildBlockNames** +### getChildBlockNames Returns an array with the child blocks of a given block. @@ -98,7 +122,7 @@ _Returns_ - `Array`: Array of child block names. -# **getCollections** +### getCollections Returns all the available collections. @@ -110,7 +134,7 @@ _Returns_ - `Object`: Collections list. -# **getDefaultBlockName** +### getDefaultBlockName Returns the name of the default block name. @@ -122,7 +146,7 @@ _Returns_ - `string?`: Default block name. -# **getDefaultBlockVariation** +### getDefaultBlockVariation Returns the default block variation for the given block type. When there are multiple variations annotated as the default one, @@ -139,7 +163,7 @@ _Returns_ - `?WPBlockVariation`: The default block variation. -# **getFreeformFallbackBlockName** +### getFreeformFallbackBlockName Returns the name of the block for handling non-block content. @@ -151,7 +175,7 @@ _Returns_ - `string?`: Name of the block for handling non-block content. -# **getGroupingBlockName** +### getGroupingBlockName Returns the name of the block for handling unregistered blocks. @@ -163,7 +187,7 @@ _Returns_ - `string?`: Name of the block for handling unregistered blocks. -# **getUnregisteredFallbackBlockName** +### getUnregisteredFallbackBlockName Returns the name of the block for handling unregistered blocks. @@ -175,7 +199,7 @@ _Returns_ - `string?`: Name of the block for handling unregistered blocks. -# **hasBlockSupport** +### hasBlockSupport Returns true if the block defines support for a feature, or false otherwise. @@ -190,7 +214,7 @@ _Returns_ - `boolean`: Whether block supports feature. -# **hasChildBlocks** +### hasChildBlocks Returns a boolean indicating if a block has child blocks or not. @@ -203,7 +227,7 @@ _Returns_ - `boolean`: True if a block contains child blocks and false otherwise. -# **hasChildBlocksWithInserterSupport** +### hasChildBlocksWithInserterSupport Returns a boolean indicating if a block has at least one child block with inserter support. @@ -216,7 +240,7 @@ _Returns_ - `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. @@ -231,13 +255,13 @@ _Returns_ - `Object[]`: Whether block type matches search term. - + ## Actions - + -# **addBlockCollection** +### addBlockCollection Returns an action object used to add block collections @@ -251,7 +275,7 @@ _Returns_ - `Object`: Action object. -# **addBlockStyles** +### addBlockStyles Returns an action object used in signalling that new block styles have been added. @@ -264,7 +288,7 @@ _Returns_ - `Object`: Action object. -# **addBlockTypes** +### addBlockTypes Returns an action object used in signalling that block types have been added. @@ -276,7 +300,7 @@ _Returns_ - `Object`: Action object. -# **addBlockVariations** +### addBlockVariations Returns an action object used in signalling that new block variations have been added. @@ -289,7 +313,7 @@ _Returns_ - `Object`: Action object. -# **removeBlockCollection** +### removeBlockCollection Returns an action object used to remove block collections @@ -301,7 +325,7 @@ _Returns_ - `Object`: Action object. -# **removeBlockStyles** +### removeBlockStyles Returns an action object used in signalling that block styles have been removed. @@ -314,7 +338,7 @@ _Returns_ - `Object`: Action object. -# **removeBlockTypes** +### removeBlockTypes Returns an action object used to remove a registered block type. @@ -326,7 +350,7 @@ _Returns_ - `Object`: Action object. -# **removeBlockVariations** +### removeBlockVariations Returns an action object used in signalling that block variations have been removed. @@ -339,7 +363,7 @@ _Returns_ - `Object`: Action object. -# **setCategories** +### setCategories Returns an action object used to set block categories. @@ -351,7 +375,7 @@ _Returns_ - `Object`: Action object. -# **setDefaultBlockName** +### setDefaultBlockName Returns an action object used to set the default block name. @@ -363,7 +387,7 @@ _Returns_ - `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. @@ -376,7 +400,7 @@ _Returns_ - `Object`: Action object. -# **setGroupingBlockName** +### setGroupingBlockName Returns an action object used to set the name of the block used when grouping other blocks @@ -390,7 +414,7 @@ _Returns_ - `Object`: Action object. -# **setUnregisteredFallbackBlockName** +### setUnregisteredFallbackBlockName Returns an action object used to set the name of the block used as a fallback for unregistered blocks. @@ -403,7 +427,7 @@ _Returns_ - `Object`: Action object. -# **updateCategory** +### updateCategory Returns an action object used to update a category. @@ -416,4 +440,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core-edit-post.md b/docs/reference-guides/data/data-core-edit-post.md index b238dbe264fc4..2042817a8c8f4 100644 --- a/docs/reference-guides/data/data-core-edit-post.md +++ b/docs/reference-guides/data/data-core-edit-post.md @@ -4,9 +4,21 @@ Namespace: `core/edit-post`. ## Selectors - + -# **getActiveGeneralSidebarName** +### areMetaBoxesInitialized + +Returns true if meta boxes are initialized. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether meta boxes are initialized. + +### getActiveGeneralSidebarName 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 @@ -25,7 +37,7 @@ _Returns_ - `?string`: Active general sidebar name. -# **getActiveMetaBoxLocations** +### getActiveMetaBoxLocations Returns an array of active meta box locations. @@ -37,7 +49,7 @@ _Returns_ - `string[]`: Active meta box locations. -# **getAllMetaBoxes** +### getAllMetaBoxes Returns the list of all the available meta boxes. @@ -49,7 +61,15 @@ _Returns_ - `Array`: List of meta boxes. -# **getEditorMode** +### getEditedPostTemplate + +Retrieves the template of the currently edited post. + +_Returns_ + +- `Object?`: Post Template. + +### getEditorMode Returns the current editing mode. @@ -61,7 +81,7 @@ _Returns_ - `string`: Editing mode. -# **getMetaBoxesPerLocation** +### getMetaBoxesPerLocation Returns the list of all the available meta boxes for a given location. @@ -74,7 +94,7 @@ _Returns_ - `?Array`: List of meta boxes. -# **getPreference** +### getPreference _Parameters_ @@ -86,7 +106,7 @@ _Returns_ - `*`: Preference Value. -# **getPreferences** +### getPreferences Returns the preferences (these preferences are persisted locally). @@ -98,7 +118,7 @@ _Returns_ - `Object`: Preferences Object. -# **hasMetaBoxes** +### hasMetaBoxes Returns true if the post is using Meta Boxes @@ -110,7 +130,7 @@ _Returns_ - `boolean`: Whether there are metaboxes or not. -# **isEditingTemplate** +### isEditingTemplate Returns true if the template editing mode is enabled. @@ -122,7 +142,7 @@ _Returns_ - `boolean`: Whether we're editing the template. -# **isEditorPanelEnabled** +### isEditorPanelEnabled Returns true if the given panel is enabled, or false otherwise. Panels are enabled by default. @@ -136,7 +156,7 @@ _Returns_ - `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. @@ -150,7 +170,7 @@ _Returns_ - `boolean`: Whether or not the panel is open. -# **isEditorPanelRemoved** +### isEditorPanelRemoved Returns true if the given panel was programmatically removed, or false otherwise. All panels are not removed by default. @@ -164,7 +184,7 @@ _Returns_ - `boolean`: Whether or not the panel is removed. -# **isEditorSidebarOpened** +### isEditorSidebarOpened Returns true if the editor sidebar is opened. @@ -176,7 +196,7 @@ _Returns_ - `boolean`: Whether the editor sidebar is opened. -# **isFeatureActive** +### isFeatureActive Returns whether the given feature is enabled or not. @@ -189,7 +209,7 @@ _Returns_ - `boolean`: Is active. -# **isInserterOpened** +### isInserterOpened Returns true if the inserter is opened. @@ -201,7 +221,19 @@ _Returns_ - `boolean`: Whether the inserter is opened. -# **isMetaBoxLocationActive** +### isListViewOpened + +Returns true if the list view is opened. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether the list view is opened. + +### isMetaBoxLocationActive Returns true if there is an active meta box in the given location, or false otherwise. @@ -215,7 +247,7 @@ _Returns_ - `boolean`: Whether the meta box location is active. -# **isMetaBoxLocationVisible** +### isMetaBoxLocationVisible Returns true if a metabox location is active and visible @@ -228,7 +260,7 @@ _Returns_ - `boolean`: Whether the meta box location is active and visible. -# **isModalActive** +### isModalActive Returns true if a modal is active, or false otherwise. @@ -241,7 +273,7 @@ _Returns_ - `boolean`: Whether the modal is active. -# **isPluginItemPinned** +### isPluginItemPinned Returns true if the plugin item is pinned to the header. When the value is not set it defaults to true. @@ -255,7 +287,7 @@ _Returns_ - `boolean`: Whether the plugin item is pinned. -# **isPluginSidebarOpened** +### isPluginSidebarOpened Returns true if the plugin sidebar is opened. @@ -267,7 +299,7 @@ _Returns_ - `boolean`: Whether the plugin sidebar is opened. -# **isPublishSidebarOpened** +### isPublishSidebarOpened Returns true if the publish sidebar is opened. @@ -279,7 +311,7 @@ _Returns_ - `boolean`: Whether the publish sidebar is open. -# **isSavingMetaBoxes** +### isSavingMetaBoxes Returns true if the Meta Boxes are being saved. @@ -291,17 +323,17 @@ _Returns_ - `boolean`: Whether the metaboxes are being saved. - + ## Actions - + -# **closeGeneralSidebar** +### closeGeneralSidebar Returns an action object signalling that the user closed the sidebar. -# **closeModal** +### closeModal Returns an action object signalling that the user closed a modal. @@ -309,7 +341,7 @@ _Returns_ - `Object`: Action object. -# **closePublishSidebar** +### closePublishSidebar Returns an action object used in signalling that the user closed the publish sidebar. @@ -318,7 +350,7 @@ _Returns_ - `Object`: Action object. -# **hideBlockTypes** +### hideBlockTypes Returns an action object used in signalling that block types by the given name(s) should be hidden. @@ -331,7 +363,11 @@ _Returns_ - `Object`: Action object. -# **metaBoxUpdatesSuccess** +### initializeMetaBoxes + +Initializes WordPress `postboxes` script and the logic for saving meta boxes. + +### metaBoxUpdatesSuccess Returns an action object used signal a successful meta box update. @@ -339,7 +375,7 @@ _Returns_ - `Object`: Action object. -# **openGeneralSidebar** +### openGeneralSidebar Returns an action object used in signalling that the user opened an editor sidebar. @@ -347,7 +383,7 @@ _Parameters_ - _name_ `?string`: Sidebar name to be opened. -# **openModal** +### openModal Returns an action object used in signalling that the user opened a modal. @@ -359,7 +395,7 @@ _Returns_ - `Object`: Action object. -# **openPublishSidebar** +### openPublishSidebar Returns an action object used in signalling that the user opened the publish sidebar. @@ -368,7 +404,7 @@ _Returns_ - `Object`: Action object -# **removeEditorPanel** +### removeEditorPanel Returns an action object used to remove a panel from the editor. @@ -380,11 +416,11 @@ _Returns_ - `Object`: Action object. -# **requestMetaBoxUpdates** +### requestMetaBoxUpdates Returns an action object used to request meta box update. -# **setAvailableMetaBoxesPerLocation** +### setAvailableMetaBoxesPerLocation Returns an action object used in signaling what Meta boxes are available in which location. @@ -393,7 +429,7 @@ _Parameters_ - _metaBoxesPerLocation_ `Object`: Meta boxes per location. -# **setIsEditingTemplate** +### setIsEditingTemplate Returns an action object used to switch to template editing. @@ -405,19 +441,33 @@ _Returns_ - `Object`: Action object. -# **setIsInserterOpened** +### setIsInserterOpened Returns an action object used to open/close the inserter. _Parameters_ -- _value_ `boolean`: A boolean representing whether the inserter should be opened or closed. +- _value_ `boolean|Object`: Whether the inserter should be opened (true) or closed (false). To specify an insertion point, use an object. +- _value.rootClientId_ `string`: The root client ID to insert at. +- _value.insertionIndex_ `number`: The index to insert at. + +_Returns_ + +- `Object`: Action object. + +### setIsListViewOpened + +Returns an action object used to open/close the list view. + +_Parameters_ + +- _isOpen_ `boolean`: A boolean representing whether the list view should be opened or closed. _Returns_ - `Object`: Action object. -# **showBlockTypes** +### showBlockTypes Returns an action object used in signalling that block types by the given name(s) should be shown. @@ -430,11 +480,11 @@ _Returns_ - `Object`: Action object. -# **switchEditorMode** +### switchEditorMode Undocumented declaration. -# **toggleEditorPanelEnabled** +### toggleEditorPanelEnabled Returns an action object used to enable or disable a panel in the editor. @@ -446,7 +496,7 @@ _Returns_ - `Object`: Action object. -# **toggleEditorPanelOpened** +### toggleEditorPanelOpened Returns an action object used to open or close a panel in the editor. @@ -458,7 +508,7 @@ _Returns_ - `Object`: Action object. -# **toggleFeature** +### toggleFeature Returns an action object used to toggle a feature flag. @@ -470,7 +520,7 @@ _Returns_ - `Object`: Action object. -# **togglePinnedPluginItem** +### togglePinnedPluginItem Returns an action object used to toggle a plugin name flag. @@ -482,7 +532,7 @@ _Returns_ - `Object`: Action object. -# **togglePublishSidebar** +### togglePublishSidebar Returns an action object used in signalling that the user toggles the publish sidebar. @@ -490,7 +540,7 @@ _Returns_ - `Object`: Action object -# **updatePreferredStyleVariations** +### updatePreferredStyleVariations Returns an action object used in signaling that a style should be auto-applied when a block is created. @@ -503,4 +553,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core-editor.md b/docs/reference-guides/data/data-core-editor.md index 87a14b0b1482f..5ada51db29c7f 100644 --- a/docs/reference-guides/data/data-core-editor.md +++ b/docs/reference-guides/data/data-core-editor.md @@ -4,15 +4,15 @@ Namespace: `core/editor`. ## Selectors - + -# **canInsertBlockType** +### canInsertBlockType _Related_ - canInsertBlockType in core/block-editor store. -# **canUserUseUnfilteredHTML** +### canUserUseUnfilteredHTML Returns whether or not the user has the unfiltered_html capability. @@ -24,7 +24,7 @@ _Returns_ - `boolean`: Whether the user can or can't post unfiltered HTML. -# **didPostSaveRequestFail** +### didPostSaveRequestFail Returns true if a previous post save was attempted but failed, or false otherwise. @@ -37,7 +37,7 @@ _Returns_ - `boolean`: Whether the post save failed. -# **didPostSaveRequestSucceed** +### didPostSaveRequestSucceed Returns true if a previous post save was attempted successfully, or false otherwise. @@ -50,7 +50,7 @@ _Returns_ - `boolean`: Whether the post was saved successfully. -# **getActivePostLock** +### getActivePostLock Returns the active post lock. @@ -62,13 +62,13 @@ _Returns_ - `Object`: The lock object. -# **getAdjacentBlockClientId** +### getAdjacentBlockClientId _Related_ - getAdjacentBlockClientId in core/block-editor store. -# **getAutosave** +### getAutosave > **Deprecated** since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector from the '@wordpress/core-data' package. @@ -84,7 +84,7 @@ _Returns_ - `?Object`: Current autosave, if exists. -# **getAutosaveAttribute** +### 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. @@ -100,97 +100,97 @@ _Returns_ - `*`: Autosave attribute value. -# **getBlock** +### getBlock _Related_ - getBlock in core/block-editor store. -# **getBlockAttributes** +### getBlockAttributes _Related_ - getBlockAttributes in core/block-editor store. -# **getBlockCount** +### getBlockCount _Related_ - getBlockCount in core/block-editor store. -# **getBlockHierarchyRootClientId** +### getBlockHierarchyRootClientId _Related_ - getBlockHierarchyRootClientId in core/block-editor store. -# **getBlockIndex** +### getBlockIndex _Related_ - getBlockIndex in core/block-editor store. -# **getBlockInsertionPoint** +### getBlockInsertionPoint _Related_ - getBlockInsertionPoint in core/block-editor store. -# **getBlockListSettings** +### getBlockListSettings _Related_ - getBlockListSettings in core/block-editor store. -# **getBlockMode** +### getBlockMode _Related_ - getBlockMode in core/block-editor store. -# **getBlockName** +### getBlockName _Related_ - getBlockName in core/block-editor store. -# **getBlockOrder** +### getBlockOrder _Related_ - getBlockOrder in core/block-editor store. -# **getBlockRootClientId** +### getBlockRootClientId _Related_ - getBlockRootClientId in core/block-editor store. -# **getBlocks** +### getBlocks _Related_ - getBlocks in core/block-editor store. -# **getBlocksByClientId** +### getBlocksByClientId _Related_ - getBlocksByClientId in core/block-editor store. -# **getBlockSelectionEnd** +### getBlockSelectionEnd _Related_ - getBlockSelectionEnd in core/block-editor store. -# **getBlockSelectionStart** +### getBlockSelectionStart _Related_ - getBlockSelectionStart in core/block-editor store. -# **getBlocksForSerialization** +### getBlocksForSerialization > **Deprecated** since Gutenberg 6.2.0. @@ -205,19 +205,19 @@ _Returns_ - `WPBlock[]`: Filtered set of blocks for save. -# **getClientIdsOfDescendants** +### getClientIdsOfDescendants _Related_ - getClientIdsOfDescendants in core/block-editor store. -# **getClientIdsWithDescendants** +### getClientIdsWithDescendants _Related_ - getClientIdsWithDescendants in core/block-editor store. -# **getCurrentPost** +### getCurrentPost Returns the post currently being edited in its last known saved state, not including unsaved edits. Returns an object containing relevant default post @@ -231,7 +231,7 @@ _Returns_ - `Object`: Post object. -# **getCurrentPostAttribute** +### getCurrentPostAttribute Returns an attribute value of the saved post. @@ -244,7 +244,7 @@ _Returns_ - `*`: Post attribute value. -# **getCurrentPostId** +### getCurrentPostId Returns the ID of the post currently being edited, or null if the post has not yet been saved. @@ -257,7 +257,7 @@ _Returns_ - `?number`: ID of current post. -# **getCurrentPostLastRevisionId** +### getCurrentPostLastRevisionId Returns the last revision ID of the post currently being edited, or null if the post has no revisions. @@ -270,7 +270,7 @@ _Returns_ - `?number`: ID of the last revision. -# **getCurrentPostRevisionsCount** +### getCurrentPostRevisionsCount Returns the number of revisions of the post currently being edited. @@ -282,7 +282,7 @@ _Returns_ - `number`: Number of revisions. -# **getCurrentPostType** +### getCurrentPostType Returns the post type of the post currently being edited. @@ -294,7 +294,7 @@ _Returns_ - `string`: Post type. -# **getEditedPostAttribute** +### 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 @@ -309,7 +309,7 @@ _Returns_ - `*`: Post attribute value. -# **getEditedPostContent** +### getEditedPostContent Returns the content of the post being edited. @@ -321,7 +321,7 @@ _Returns_ - `string`: Post content. -# **getEditedPostPreviewLink** +### getEditedPostPreviewLink Returns the post preview link @@ -333,7 +333,7 @@ _Returns_ - `string?`: Preview Link. -# **getEditedPostSlug** +### getEditedPostSlug Returns the slug for the post being edited, preferring a manually edited value if one exists, then a sanitized version of the current post title, and @@ -347,7 +347,7 @@ _Returns_ - `string`: The current slug to be displayed in the editor -# **getEditedPostVisibility** +### 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 @@ -361,7 +361,7 @@ _Returns_ - `string`: Post visibility. -# **getEditorBlocks** +### getEditorBlocks Return the current block list. @@ -373,7 +373,7 @@ _Returns_ - `Array`: Block list. -# **getEditorSelection** +### getEditorSelection Returns the current selection. @@ -385,7 +385,7 @@ _Returns_ - `WPBlockSelection`: The selection end. -# **getEditorSelectionEnd** +### getEditorSelectionEnd > **Deprecated** since Gutenberg 10.0.0. @@ -399,7 +399,7 @@ _Returns_ - `WPBlockSelection`: The selection end. -# **getEditorSelectionStart** +### getEditorSelectionStart > **Deprecated** since Gutenberg 10.0.0. @@ -413,7 +413,7 @@ _Returns_ - `WPBlockSelection`: The selection start. -# **getEditorSettings** +### getEditorSettings Returns the post editor settings. @@ -425,61 +425,61 @@ _Returns_ - `Object`: The editor settings object. -# **getFirstMultiSelectedBlockClientId** +### getFirstMultiSelectedBlockClientId _Related_ - getFirstMultiSelectedBlockClientId in core/block-editor store. -# **getGlobalBlockCount** +### getGlobalBlockCount _Related_ - getGlobalBlockCount in core/block-editor store. -# **getInserterItems** +### getInserterItems _Related_ - getInserterItems in core/block-editor store. -# **getLastMultiSelectedBlockClientId** +### getLastMultiSelectedBlockClientId _Related_ - getLastMultiSelectedBlockClientId in core/block-editor store. -# **getMultiSelectedBlockClientIds** +### getMultiSelectedBlockClientIds _Related_ - getMultiSelectedBlockClientIds in core/block-editor store. -# **getMultiSelectedBlocks** +### getMultiSelectedBlocks _Related_ - getMultiSelectedBlocks in core/block-editor store. -# **getMultiSelectedBlocksEndClientId** +### getMultiSelectedBlocksEndClientId _Related_ - getMultiSelectedBlocksEndClientId in core/block-editor store. -# **getMultiSelectedBlocksStartClientId** +### getMultiSelectedBlocksStartClientId _Related_ - getMultiSelectedBlocksStartClientId in core/block-editor store. -# **getNextBlockClientId** +### getNextBlockClientId _Related_ - getNextBlockClientId in core/block-editor store. -# **getPermalink** +### getPermalink Returns the permalink for the post. @@ -491,7 +491,7 @@ _Returns_ - `?string`: The permalink, or null if the post is not viewable. -# **getPermalinkParts** +### getPermalinkParts Returns the permalink for a post, split into it's three parts: the prefix, the postName, and the suffix. @@ -504,7 +504,7 @@ _Returns_ - `Object`: An object containing the prefix, postName, and suffix for the permalink, or null if the post is not viewable. -# **getPostEdits** +### getPostEdits Returns any post values which have been changed in the editor but not yet been saved. @@ -517,7 +517,7 @@ _Returns_ - `Object`: Object of key value pairs comprising unsaved edits. -# **getPostLockUser** +### getPostLockUser Returns details about the post lock user. @@ -529,13 +529,13 @@ _Returns_ - `Object`: A user object. -# **getPreviousBlockClientId** +### getPreviousBlockClientId _Related_ - getPreviousBlockClientId in core/block-editor store. -# **getReferenceByDistinctEdits** +### getReferenceByDistinctEdits > **Deprecated** since Gutenberg 6.5.0. @@ -558,38 +558,38 @@ _Returns_ - `*`: A value whose reference will change only when an edit occurs. -# **getSelectedBlock** +### getSelectedBlock _Related_ - getSelectedBlock in core/block-editor store. -# **getSelectedBlockClientId** +### getSelectedBlockClientId _Related_ - getSelectedBlockClientId in core/block-editor store. -# **getSelectedBlockCount** +### getSelectedBlockCount _Related_ - getSelectedBlockCount in core/block-editor store. -# **getSelectedBlocksInitialCaretPosition** +### getSelectedBlocksInitialCaretPosition _Related_ - getSelectedBlocksInitialCaretPosition in core/block-editor store. -# **getStateBeforeOptimisticTransaction** +### getStateBeforeOptimisticTransaction > **Deprecated** since Gutenberg 9.7.0. Returns state object prior to a specified optimist transaction ID, or `null` if the transaction corresponding to the given ID cannot be found. -# **getSuggestedPostFormat** +### getSuggestedPostFormat 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 @@ -603,19 +603,19 @@ _Returns_ - `?string`: Suggested post format. -# **getTemplate** +### getTemplate _Related_ - getTemplate in core/block-editor store. -# **getTemplateLock** +### getTemplateLock _Related_ - getTemplateLock in core/block-editor store. -# **hasAutosave** +### hasAutosave > **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. @@ -629,7 +629,7 @@ _Returns_ - `boolean`: Whether there is an existing autosave. -# **hasChangedContent** +### hasChangedContent Returns true if content includes unsaved changes, or false otherwise. @@ -641,7 +641,7 @@ _Returns_ - `boolean`: Whether content includes unsaved changes. -# **hasEditorRedo** +### hasEditorRedo Returns true if any future editor history snapshots exist, or false otherwise. @@ -654,7 +654,7 @@ _Returns_ - `boolean`: Whether redo history exists. -# **hasEditorUndo** +### hasEditorUndo Returns true if any past editor history snapshots exist, or false otherwise. @@ -666,19 +666,19 @@ _Returns_ - `boolean`: Whether undo history exists. -# **hasInserterItems** +### hasInserterItems _Related_ - hasInserterItems in core/block-editor store. -# **hasMultiSelection** +### hasMultiSelection _Related_ - hasMultiSelection in core/block-editor store. -# **hasNonPostEntityChanges** +### hasNonPostEntityChanges Returns true if there are unsaved edits for entities other than the editor's post, and false otherwise. @@ -691,32 +691,32 @@ _Returns_ - `boolean`: Whether there are edits or not. -# **hasSelectedBlock** +### hasSelectedBlock _Related_ - hasSelectedBlock in core/block-editor store. -# **hasSelectedInnerBlock** +### hasSelectedInnerBlock _Related_ - hasSelectedInnerBlock in core/block-editor store. -# **inSomeHistory** +### inSomeHistory > **Deprecated** since Gutenberg 9.7.0. Returns true if an optimistic transaction is pending commit, for which the before state satisfies the given predicate function. -# **isAncestorMultiSelected** +### isAncestorMultiSelected _Related_ - isAncestorMultiSelected in core/block-editor store. -# **isAutosavingPost** +### isAutosavingPost Returns true if the post is autosaving, or false otherwise. @@ -728,43 +728,43 @@ _Returns_ - `boolean`: Whether the post is autosaving. -# **isBlockInsertionPointVisible** +### isBlockInsertionPointVisible _Related_ - isBlockInsertionPointVisible in core/block-editor store. -# **isBlockMultiSelected** +### isBlockMultiSelected _Related_ - isBlockMultiSelected in core/block-editor store. -# **isBlockSelected** +### isBlockSelected _Related_ - isBlockSelected in core/block-editor store. -# **isBlockValid** +### isBlockValid _Related_ - isBlockValid in core/block-editor store. -# **isBlockWithinSelection** +### isBlockWithinSelection _Related_ - isBlockWithinSelection in core/block-editor store. -# **isCaretWithinFormattedText** +### isCaretWithinFormattedText _Related_ - isCaretWithinFormattedText in core/block-editor store. -# **isCleanNewPost** +### 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). @@ -777,7 +777,7 @@ _Returns_ - `boolean`: Whether new post and unsaved values exist. -# **isCurrentPostPending** +### isCurrentPostPending Returns true if post is pending review. @@ -789,7 +789,7 @@ _Returns_ - `boolean`: Whether current post is pending review. -# **isCurrentPostPublished** +### isCurrentPostPublished Return true if the current post has already been published. @@ -802,7 +802,7 @@ _Returns_ - `boolean`: Whether the post has been published. -# **isCurrentPostScheduled** +### isCurrentPostScheduled Returns true if post is already scheduled. @@ -814,7 +814,7 @@ _Returns_ - `boolean`: Whether current post is scheduled to be posted. -# **isEditedPostAutosaveable** +### isEditedPostAutosaveable Returns true if the post can be autosaved, or false otherwise. @@ -827,7 +827,7 @@ _Returns_ - `boolean`: Whether the post can be autosaved. -# **isEditedPostBeingScheduled** +### isEditedPostBeingScheduled Return true if the post being edited is being scheduled. Preferring the unsaved status values. @@ -840,7 +840,7 @@ _Returns_ - `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). @@ -858,7 +858,7 @@ _Returns_ - `boolean`: Whether the edited post has a floating date value. -# **isEditedPostDirty** +### isEditedPostDirty Returns true if there are unsaved values for the current edit session, or false if the editing state matches the saved or new post. @@ -871,7 +871,7 @@ _Returns_ - `boolean`: Whether unsaved values exist. -# **isEditedPostEmpty** +### isEditedPostEmpty 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 @@ -885,7 +885,7 @@ _Returns_ - `boolean`: Whether post has content. -# **isEditedPostNew** +### isEditedPostNew Returns true if the currently edited post is yet to be saved, or false if the post has been saved. @@ -898,7 +898,7 @@ _Returns_ - `boolean`: Whether the post is new. -# **isEditedPostPublishable** +### isEditedPostPublishable Return true if the post being edited can be published. @@ -910,7 +910,7 @@ _Returns_ - `boolean`: Whether the post can been published. -# **isEditedPostSaveable** +### isEditedPostSaveable 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. @@ -923,19 +923,19 @@ _Returns_ - `boolean`: Whether the post can be saved. -# **isFirstMultiSelectedBlock** +### isFirstMultiSelectedBlock _Related_ - isFirstMultiSelectedBlock in core/block-editor store. -# **isMultiSelecting** +### isMultiSelecting _Related_ - isMultiSelecting in core/block-editor store. -# **isPermalinkEditable** +### isPermalinkEditable Returns whether the permalink is editable or not. @@ -947,7 +947,7 @@ _Returns_ - `boolean`: Whether or not the permalink is editable. -# **isPostAutosavingLocked** +### isPostAutosavingLocked Returns whether post autosaving is locked. @@ -959,7 +959,7 @@ _Returns_ - `boolean`: Is locked. -# **isPostLocked** +### isPostLocked Returns whether the post is locked. @@ -971,7 +971,7 @@ _Returns_ - `boolean`: Is locked. -# **isPostLockTakeover** +### isPostLockTakeover Returns whether the edition of the post has been taken over. @@ -983,7 +983,7 @@ _Returns_ - `boolean`: Is post lock takeover. -# **isPostSavingLocked** +### isPostSavingLocked Returns whether post saving is locked. @@ -995,7 +995,7 @@ _Returns_ - `boolean`: Is locked. -# **isPreviewingPost** +### isPreviewingPost Returns true if the post is being previewed, or false otherwise. @@ -1007,7 +1007,7 @@ _Returns_ - `boolean`: Whether the post is being previewed. -# **isPublishingPost** +### isPublishingPost Returns true if the post is being published, or false otherwise. @@ -1019,7 +1019,7 @@ _Returns_ - `boolean`: Whether post is being published. -# **isPublishSidebarEnabled** +### isPublishSidebarEnabled Returns whether the pre-publish panel should be shown or skipped when the user clicks the "publish" button. @@ -1032,7 +1032,7 @@ _Returns_ - `boolean`: Whether the pre-publish panel should be shown or not. -# **isSavingPost** +### isSavingPost Returns true if the post is currently being saved, or false otherwise. @@ -1044,31 +1044,31 @@ _Returns_ - `boolean`: Whether post is being saved. -# **isSelectionEnabled** +### isSelectionEnabled _Related_ - isSelectionEnabled in core/block-editor store. -# **isTyping** +### isTyping _Related_ - isTyping in core/block-editor store. -# **isValidTemplate** +### isValidTemplate _Related_ - isValidTemplate in core/block-editor store. - + ## Actions - + -# **autosave** +### autosave Action generator used in signalling that the post should autosave. This includes server-side autosaving (default) and client-side (a.k.a. local) @@ -1079,13 +1079,13 @@ _Parameters_ - _options_ `Object?`: Extra flags to identify the autosave. -# **clearSelectedBlock** +### clearSelectedBlock _Related_ - clearSelectedBlock in core/block-editor store. -# **createUndoLevel** +### createUndoLevel Returns an action object used in signalling that undo history record should be created. @@ -1094,7 +1094,7 @@ _Returns_ - `Object`: Action object. -# **disablePublishSidebar** +### disablePublishSidebar Returns an action object used in signalling that the user has disabled the publish sidebar. @@ -1103,7 +1103,7 @@ _Returns_ - `Object`: Action object -# **editPost** +### editPost Returns an action object used in signalling that attributes of the post have been edited. @@ -1113,7 +1113,7 @@ _Parameters_ - _edits_ `Object`: Post attributes to edit. - _options_ `Object`: Options for the edit. -# **enablePublishSidebar** +### enablePublishSidebar Returns an action object used in signalling that the user has enabled the publish sidebar. @@ -1122,43 +1122,43 @@ _Returns_ - `Object`: Action object -# **enterFormattedText** +### enterFormattedText _Related_ - enterFormattedText in core/block-editor store. -# **exitFormattedText** +### exitFormattedText _Related_ - exitFormattedText in core/block-editor store. -# **hideInsertionPoint** +### hideInsertionPoint _Related_ - hideInsertionPoint in core/block-editor store. -# **insertBlock** +### insertBlock _Related_ - insertBlock in core/block-editor store. -# **insertBlocks** +### insertBlocks _Related_ - insertBlocks in core/block-editor store. -# **insertDefaultBlock** +### insertDefaultBlock _Related_ - insertDefaultBlock in core/block-editor store. -# **lockPostAutosaving** +### lockPostAutosaving Returns an action object used to signal that post autosaving is locked. @@ -1175,7 +1175,7 @@ _Returns_ - `Object`: Action object -# **lockPostSaving** +### lockPostSaving Returns an action object used to signal that post saving is locked. @@ -1222,76 +1222,76 @@ _Returns_ - `Object`: Action object -# **mergeBlocks** +### mergeBlocks _Related_ - mergeBlocks in core/block-editor store. -# **moveBlocksDown** +### moveBlocksDown _Related_ - moveBlocksDown in core/block-editor store. -# **moveBlocksUp** +### moveBlocksUp _Related_ - moveBlocksUp in core/block-editor store. -# **moveBlockToPosition** +### moveBlockToPosition _Related_ - moveBlockToPosition in core/block-editor store. -# **multiSelect** +### multiSelect _Related_ - multiSelect in core/block-editor store. -# **receiveBlocks** +### receiveBlocks _Related_ - receiveBlocks in core/block-editor store. -# **redo** +### redo Returns an action object used in signalling that undo history should restore last popped state. -# **refreshPost** +### refreshPost Action generator for handling refreshing the current post. -# **removeBlock** +### removeBlock _Related_ - removeBlock in core/block-editor store. -# **removeBlocks** +### removeBlocks _Related_ - removeBlocks in core/block-editor store. -# **replaceBlock** +### replaceBlock _Related_ - replaceBlock in core/block-editor store. -# **replaceBlocks** +### replaceBlocks _Related_ - replaceBlocks in core/block-editor store. -# **resetAutosave** +### resetAutosave > **Deprecated** since 5.6. Callers should use the `receiveAutosaves( postId, autosave )` selector from the '@wordpress/core-data' package. @@ -1306,13 +1306,13 @@ _Returns_ - `Object`: Action object. -# **resetBlocks** +### resetBlocks _Related_ - resetBlocks in core/block-editor store. -# **resetEditorBlocks** +### resetEditorBlocks Returns an action object used to signal that the blocks have been updated. @@ -1321,7 +1321,7 @@ _Parameters_ - _blocks_ `Array`: Block Array. - _options_ `?Object`: Optional options. -# **resetPost** +### resetPost Returns an action object used in signalling that the latest version of the post has been received, either by initialization or save. @@ -1334,7 +1334,7 @@ _Returns_ - `Object`: Action object. -# **savePost** +### savePost Action generator for saving the current post in the editor. @@ -1342,19 +1342,19 @@ _Parameters_ - _options_ `Object`: -# **selectBlock** +### selectBlock _Related_ - selectBlock in core/block-editor store. -# **setTemplateValidity** +### setTemplateValidity _Related_ - setTemplateValidity in core/block-editor store. -# **setupEditor** +### setupEditor Returns an action generator used in signalling that editor has initialized with the specified post object and editor settings. @@ -1365,7 +1365,7 @@ _Parameters_ - _edits_ `Object`: Initial edited attributes object. - _template_ `Array?`: Block Template. -# **setupEditorState** +### setupEditorState Returns an action object used to setup the editor state when first opening an editor. @@ -1378,63 +1378,63 @@ _Returns_ - `Object`: Action object. -# **showInsertionPoint** +### showInsertionPoint _Related_ - showInsertionPoint in core/block-editor store. -# **startMultiSelect** +### startMultiSelect _Related_ - startMultiSelect in core/block-editor store. -# **startTyping** +### startTyping _Related_ - startTyping in core/block-editor store. -# **stopMultiSelect** +### stopMultiSelect _Related_ - stopMultiSelect in core/block-editor store. -# **stopTyping** +### stopTyping _Related_ - stopTyping in core/block-editor store. -# **synchronizeTemplate** +### synchronizeTemplate _Related_ - synchronizeTemplate in core/block-editor store. -# **toggleBlockMode** +### toggleBlockMode _Related_ - toggleBlockMode in core/block-editor store. -# **toggleSelection** +### toggleSelection _Related_ - toggleSelection in core/block-editor store. -# **trashPost** +### trashPost Action generator for trashing the current post in the editor. -# **undo** +### undo Returns an action object used in signalling that undo history should pop. -# **unlockPostAutosaving** +### unlockPostAutosaving Returns an action object used to signal that post autosaving is unlocked. @@ -1451,7 +1451,7 @@ _Returns_ - `Object`: Action object -# **unlockPostSaving** +### unlockPostSaving Returns an action object used to signal that post saving is unlocked. @@ -1468,29 +1468,29 @@ _Returns_ - `Object`: Action object -# **updateBlock** +### updateBlock _Related_ - updateBlock in core/block-editor store. -# **updateBlockAttributes** +### updateBlockAttributes _Related_ - updateBlockAttributes in core/block-editor store. -# **updateBlockListSettings** +### updateBlockListSettings _Related_ - updateBlockListSettings in core/block-editor store. -# **updateEditorSettings** +### updateEditorSettings Undocumented declaration. -# **updatePost** +### updatePost > **Deprecated** since Gutenberg 9.7.0. @@ -1501,7 +1501,7 @@ _Returns_ - `Object`: Action object. -# **updatePostLock** +### updatePostLock Returns an action object used to lock the editor. @@ -1513,4 +1513,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core-keyboard-shortcuts.md b/docs/reference-guides/data/data-core-keyboard-shortcuts.md index 044bd248ecb12..512668650d04b 100644 --- a/docs/reference-guides/data/data-core-keyboard-shortcuts.md +++ b/docs/reference-guides/data/data-core-keyboard-shortcuts.md @@ -4,9 +4,13 @@ Namespace: `core/keyboard-shortcuts`. ## Selectors - + -# **getAllShortcutRawKeyCombinations** +### getAllShortcutKeyCombinations + +Undocumented declaration. + +### getAllShortcutRawKeyCombinations Returns the raw representation of all the keyboard combinations of a given shortcut name. @@ -19,7 +23,7 @@ _Returns_ - `string[]`: Shortcuts. -# **getCategoryShortcuts** +### getCategoryShortcuts Returns the shortcut names list for a given category name. @@ -32,7 +36,7 @@ _Returns_ - `string[]`: Shortcut names. -# **getShortcutAliases** +### getShortcutAliases Returns the aliases for a given shortcut name. @@ -45,7 +49,7 @@ _Returns_ - `WPShortcutKeyCombination[]`: Key combinations. -# **getShortcutDescription** +### getShortcutDescription Returns the shortcut description given its name. @@ -58,7 +62,7 @@ _Returns_ - `string?`: Shortcut description. -# **getShortcutKeyCombination** +### getShortcutKeyCombination Returns the main key combination for a given shortcut name. @@ -71,7 +75,7 @@ _Returns_ - `WPShortcutKeyCombination?`: Key combination. -# **getShortcutRepresentation** +### getShortcutRepresentation Returns a string representing the main key combination for a given shortcut name. @@ -85,13 +89,13 @@ _Returns_ - `string?`: Shortcut representation. - + ## Actions - + -# **registerShortcut** +### registerShortcut Returns an action object used to register a new keyboard shortcut. @@ -103,7 +107,7 @@ _Returns_ - `Object`: action. -# **unregisterShortcut** +### unregisterShortcut Returns an action object used to unregister a keyboard shortcut. @@ -115,4 +119,4 @@ _Returns_ - `Object`: action. - + diff --git a/docs/reference-guides/data/data-core-notices.md b/docs/reference-guides/data/data-core-notices.md index 5e2675afeb447..69470c54b7ccd 100644 --- a/docs/reference-guides/data/data-core-notices.md +++ b/docs/reference-guides/data/data-core-notices.md @@ -4,9 +4,9 @@ Namespace: `core/notices`. ## Selectors - + -# **getNotices** +### getNotices Returns all notices as an array, optionally for a given context. Defaults to the global context. @@ -20,13 +20,13 @@ _Returns_ - `WPNotice[]`: Array of notices. - + ## Actions - + -# **createErrorNotice** +### createErrorNotice Returns an action object used in signalling that an error notice is to be created. Refer to `createNotice` for options documentation. @@ -44,7 +44,7 @@ _Returns_ - `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. @@ -62,7 +62,7 @@ _Returns_ - `Object`: Action object. -# **createNotice** +### createNotice Returns an action object used in signalling that a notice is to be created. @@ -85,7 +85,7 @@ _Returns_ - `Object`: Action object. -# **createSuccessNotice** +### createSuccessNotice Returns an action object used in signalling that a success notice is to be created. Refer to `createNotice` for options documentation. @@ -103,7 +103,7 @@ _Returns_ - `Object`: Action object. -# **createWarningNotice** +### createWarningNotice Returns an action object used in signalling that a warning notice is to be created. Refer to `createNotice` for options documentation. @@ -121,7 +121,7 @@ _Returns_ - `Object`: Action object. -# **removeNotice** +### removeNotice Returns an action object used in signalling that a notice is to be removed. @@ -134,4 +134,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core-nux.md b/docs/reference-guides/data/data-core-nux.md index 3f65bbc359c8a..4d2e8a0d98d54 100644 --- a/docs/reference-guides/data/data-core-nux.md +++ b/docs/reference-guides/data/data-core-nux.md @@ -4,9 +4,9 @@ Namespace: `core/nux`. ## Selectors - + -# **areTipsEnabled** +### areTipsEnabled Returns whether or not tips are globally enabled. @@ -18,7 +18,7 @@ _Returns_ - `boolean`: Whether tips are globally enabled. -# **getAssociatedGuide** +### getAssociatedGuide Returns an object describing the guide, if any, that the given tip is a part of. @@ -32,7 +32,7 @@ _Returns_ - `?NUXGuideInfo`: Information about the associated guide. -# **isTipVisible** +### 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 @@ -47,13 +47,13 @@ _Returns_ - `boolean`: Whether or not the given tip is showing. - + ## Actions - + -# **disableTips** +### disableTips Returns an action object that, when dispatched, prevents all tips from showing again. @@ -62,7 +62,7 @@ _Returns_ - `Object`: Action object. -# **dismissTip** +### dismissTip Returns an action object that, when dispatched, dismisses the given tip. A dismissed tip will not show again. @@ -75,7 +75,7 @@ _Returns_ - `Object`: Action object. -# **enableTips** +### enableTips Returns an action object that, when dispatched, makes all tips show again. @@ -83,7 +83,7 @@ _Returns_ - `Object`: Action object. -# **triggerGuide** +### triggerGuide Returns an action object that, when dispatched, presents a guide that takes the user through a series of tips step by step. @@ -96,4 +96,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core-viewport.md b/docs/reference-guides/data/data-core-viewport.md index c84524dc9b2f4..0764429334a08 100644 --- a/docs/reference-guides/data/data-core-viewport.md +++ b/docs/reference-guides/data/data-core-viewport.md @@ -4,9 +4,9 @@ Namespace: `core/viewport`. ## Selectors - + -# **isViewportMatch** +### isViewportMatch Returns true if the viewport matches the given query, or false otherwise. @@ -26,13 +26,13 @@ _Returns_ - `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 @@ -46,4 +46,4 @@ _Returns_ - `Object`: Action object. - + diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index c2545d9645e24..bf72387cd62b0 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -4,9 +4,9 @@ Namespace: `core`. ## Selectors - + -# **canUser** +### canUser Returns whether the current user can perform the given action on the given REST resource. @@ -27,7 +27,27 @@ _Returns_ - `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. -# **getAuthors** +### canUserEditEntityRecord + +Returns whether the current user can edit the given entity. + +Calling this may trigger an OPTIONS request to the REST API via the +`canUser()` resolver. + + + +_Parameters_ + +- _state_ `Object`: Data state. +- _kind_ `string`: Entity kind. +- _name_ `string`: Entity name. +- _recordId_ `string`: Record's id. + +_Returns_ + +- `boolean|undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. + +### getAuthors Returns all available authors. @@ -40,7 +60,7 @@ _Returns_ - `Array`: Authors list. -# **getAutosave** +### getAutosave Returns the autosave for the post and author. @@ -55,7 +75,7 @@ _Returns_ - `?Object`: The autosave for the post and author. -# **getAutosaves** +### getAutosaves Returns the latest autosaves for the post. @@ -72,7 +92,7 @@ _Returns_ - `?Array`: An array of autosaves for the post, or undefined if there is none. -# **getCurrentTheme** +### getCurrentTheme Return the current theme. @@ -84,7 +104,7 @@ _Returns_ - `Object`: The current theme. -# **getCurrentUser** +### getCurrentUser Returns the current user. @@ -96,7 +116,7 @@ _Returns_ - `Object`: Current user object. -# **getEditedEntityRecord** +### getEditedEntityRecord Returns the specified entity record, merged with its edits. @@ -111,7 +131,7 @@ _Returns_ - `Object?`: The entity record, merged with its edits. -# **getEmbedPreview** +### getEmbedPreview Returns the embed preview for the given URL. @@ -124,7 +144,7 @@ _Returns_ - `*`: 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. @@ -135,9 +155,9 @@ _Parameters_ _Returns_ -- `boolean`: Whether the entities are loaded +- `Array`: Array of entities with config matching kind. -# **getEntity** +### getEntity Returns the entity object given its kind and name. @@ -151,7 +171,7 @@ _Returns_ - `Object`: Entity -# **getEntityRecord** +### getEntityRecord Returns the Entity's record object by key. Returns `null` if the value is not yet received, undefined if the value entity is known to not exist, or the @@ -169,7 +189,7 @@ _Returns_ - `Object?`: Record. -# **getEntityRecordEdits** +### getEntityRecordEdits Returns the specified entity record's edits. @@ -184,7 +204,7 @@ _Returns_ - `Object?`: The entity record's edits. -# **getEntityRecordNonTransientEdits** +### getEntityRecordNonTransientEdits Returns the specified entity record's non transient edits. @@ -203,7 +223,7 @@ _Returns_ - `Object?`: The entity record's non transient edits. -# **getEntityRecords** +### getEntityRecords Returns the Entity's records. @@ -218,7 +238,7 @@ _Returns_ - `?Array`: Records. -# **getLastEntityDeleteError** +### getLastEntityDeleteError Returns the specified entity record's last delete error. @@ -233,7 +253,7 @@ _Returns_ - `Object?`: The entity record's save error. -# **getLastEntitySaveError** +### getLastEntitySaveError Returns the specified entity record's last save error. @@ -248,7 +268,7 @@ _Returns_ - `Object?`: The entity record's save error. -# **getRawEntityRecord** +### getRawEntityRecord Returns the entity's record object by key, with its attributes mapped to their raw values. @@ -264,7 +284,7 @@ _Returns_ - `Object?`: Object with the entity's raw attributes. -# **getRedoEdit** +### getRedoEdit Returns the next edit from the current undo offset for the entity records edits history, if any. @@ -277,7 +297,7 @@ _Returns_ - `Object?`: The edit. -# **getReferenceByDistinctEdits** +### 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 @@ -298,7 +318,7 @@ _Returns_ - `*`: A value whose reference will change only when an edit occurs. -# **getThemeSupports** +### getThemeSupports Return theme supports data in the index. @@ -310,7 +330,7 @@ _Returns_ - `*`: Index data. -# **getUndoEdit** +### getUndoEdit Returns the previous edit from the current undo offset for the entity records edits history, if any. @@ -323,7 +343,7 @@ _Returns_ - `Object?`: The edit. -# **getUserQueryResults** +### getUserQueryResults Returns all the users returned by a query ID. @@ -336,7 +356,7 @@ _Returns_ - `Array`: Users list. -# **hasEditsForEntityRecord** +### hasEditsForEntityRecord Returns true if the specified entity record has edits, and false otherwise. @@ -352,7 +372,7 @@ _Returns_ - `boolean`: Whether the entity record has edits or not. -# **hasEntityRecords** +### hasEntityRecords Returns true if records have been received for the given set of parameters, or false otherwise. @@ -368,7 +388,7 @@ _Returns_ - `boolean`: Whether entity records have been received. -# **hasFetchedAutosaves** +### hasFetchedAutosaves Returns true if the REST request for autosaves has completed. @@ -382,7 +402,7 @@ _Returns_ - `boolean`: True if the REST request was completed. False otherwise. -# **hasRedo** +### hasRedo Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise. @@ -395,7 +415,7 @@ _Returns_ - `boolean`: Whether there is a next edit or not. -# **hasUndo** +### hasUndo Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise. @@ -408,26 +428,7 @@ _Returns_ - `boolean`: Whether there is a previous edit or not. -# **hasUploadPermissions** - -> **Deprecated** since 5.0. Callers should use the more generic `canUser()` selector instead of `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`. - -Returns whether the current user can upload media. - -Calling this may trigger an OPTIONS request to the REST API via the -`canUser()` resolver. - - - -_Parameters_ - -- _state_ `Object`: Data state. - -_Returns_ - -- `boolean`: Whether or not the user can upload media. Defaults to `true` if the OPTIONS request is being made. - -# **isAutosavingEntityRecord** +### isAutosavingEntityRecord Returns true if the specified entity record is autosaving, and false otherwise. @@ -442,7 +443,7 @@ _Returns_ - `boolean`: Whether the entity record is autosaving or not. -# **isDeletingEntityRecord** +### isDeletingEntityRecord Returns true if the specified entity record is deleting, and false otherwise. @@ -457,7 +458,7 @@ _Returns_ - `boolean`: Whether the entity record is deleting or not. -# **isPreviewEmbedFallback** +### isPreviewEmbedFallback Determines if the returned preview is an oEmbed link fallback. @@ -474,7 +475,7 @@ _Returns_ - `boolean`: Is the preview for the URL an oEmbed link fallback. -# **isRequestingEmbedPreview** +### isRequestingEmbedPreview Returns true if a request is in progress for embed preview data, or false otherwise. @@ -488,7 +489,7 @@ _Returns_ - `boolean`: Whether a request is in progress for an embed preview. -# **isSavingEntityRecord** +### isSavingEntityRecord Returns true if the specified entity record is saving, and false otherwise. @@ -503,13 +504,13 @@ _Returns_ - `boolean`: Whether the entity record is saving or not. - + ## Actions - + -# **addEntities** +### addEntities Returns an action object used in adding new entities. @@ -521,7 +522,7 @@ _Returns_ - `Object`: Action object. -# **deleteEntityRecord** +### deleteEntityRecord Action triggered to delete an entity record. @@ -534,7 +535,7 @@ _Parameters_ - _options_ `[Object]`: Delete options. - _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. -# **editEntityRecord** +### editEntityRecord Returns an action object that triggers an edit to an entity record. @@ -552,7 +553,7 @@ _Returns_ - `Object`: Action object. -# **receiveAutosaves** +### receiveAutosaves Returns an action object used in signalling that the autosaves for a post have been received. @@ -566,7 +567,7 @@ _Returns_ - `Object`: Action object. -# **receiveCurrentTheme** +### receiveCurrentTheme Returns an action object used in signalling that the current theme has been received. @@ -578,7 +579,7 @@ _Returns_ - `Object`: Action object. -# **receiveCurrentUser** +### receiveCurrentUser Returns an action used in signalling that the current user has been received. @@ -590,7 +591,7 @@ _Returns_ - `Object`: Action object. -# **receiveEmbedPreview** +### receiveEmbedPreview Returns an action object used in signalling that the preview data for a given URl has been received. @@ -604,7 +605,7 @@ _Returns_ - `Object`: Action object. -# **receiveEntityRecords** +### receiveEntityRecords Returns an action object used in signalling that entity records have been received. @@ -621,7 +622,7 @@ _Returns_ - `Object`: Action object. -# **receiveThemeSupports** +### receiveThemeSupports Returns an action object used in signalling that the index has been received. @@ -633,7 +634,7 @@ _Returns_ - `Object`: Action object. -# **receiveUploadPermissions** +### receiveUploadPermissions Returns an action object used in signalling that Upload permissions have been received. @@ -645,7 +646,7 @@ _Returns_ - `Object`: Action object. -# **receiveUserPermission** +### receiveUserPermission Returns an action object used in signalling that the current user has permission to perform an action on a REST resource. @@ -659,7 +660,7 @@ _Returns_ - `Object`: Action object. -# **receiveUserQuery** +### receiveUserQuery Returns an action object used in signalling that authors have been received. @@ -672,12 +673,12 @@ _Returns_ - `Object`: Action object. -# **redo** +### redo Action triggered to redo the last undoed edit to an entity record, if any. -# **saveEditedEntityRecord** +### saveEditedEntityRecord Action triggered to save an entity record's edits. @@ -688,7 +689,7 @@ _Parameters_ - _recordId_ `Object`: ID of the record. - _options_ `Object`: Saving options. -# **saveEntityRecord** +### saveEntityRecord Action triggered to save an entity record. @@ -701,9 +702,9 @@ _Parameters_ - _options.isAutosave_ `[boolean]`: Whether this is an autosave. - _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. -# **undo** +### undo Action triggered to undo the last edit to an entity record, if any. - + diff --git a/lib/block-supports/duotone.php b/lib/block-supports/duotone.php index f3b4743832f0a..aa38c55f4bd5b 100644 --- a/lib/block-supports/duotone.php +++ b/lib/block-supports/duotone.php @@ -351,7 +351,15 @@ function ( $selector ) use ( $duotone_id ) { 1 ); - return $content . $duotone; + add_action( + // Ideally we should use wp_head, but SVG defs can't be put in there. + 'wp_footer', + function () use ( $duotone ) { + echo $duotone; + } + ); + + return $content; } // Register the block support. diff --git a/lib/block-supports/layout.php b/lib/block-supports/layout.php index 1b1eec679c80a..10ccb6ccb1ed0 100644 --- a/lib/block-supports/layout.php +++ b/lib/block-supports/layout.php @@ -86,7 +86,17 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) { 1 ); - return $content . ''; + // Ideally styles should be loaded in the head, but blocks may be parsed + // after that, so loading in the footer for now. + // See https://core.trac.wordpress.org/ticket/53494. + add_action( + 'wp_footer', + function () use ( $style ) { + echo ''; + } + ); + + return $content; } // Register the block support. diff --git a/package-lock.json b/package-lock.json index f369c8901aeca..b3a8e4ed0ae1d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13648,6 +13648,7 @@ "@wordpress/core-data": "file:packages/core-data", "@wordpress/data": "file:packages/data", "@wordpress/data-controls": "file:packages/data-controls", + "@wordpress/dom": "file:packages/dom", "@wordpress/element": "file:packages/element", "@wordpress/hooks": "file:packages/hooks", "@wordpress/i18n": "file:packages/i18n", diff --git a/packages/a11y/README.md b/packages/a11y/README.md index 5f44a3d22cf39..b0a51047c73dc 100644 --- a/packages/a11y/README.md +++ b/packages/a11y/README.md @@ -16,11 +16,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If -# **setup** +### setup Create the live regions. -# **speak** +### speak Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. This module is inspired by the `speak` function in `wp-a11y.js`. @@ -42,7 +42,6 @@ _Parameters_ - _message_ `string`: The message to be announced by assistive technologies. - _ariaLive_ `[string]`: The politeness level for aria-live; default: 'polite'. - ### Background diff --git a/packages/autop/README.md b/packages/autop/README.md index 43d6a0ca123d1..1bc8b5495db6c 100644 --- a/packages/autop/README.md +++ b/packages/autop/README.md @@ -16,7 +16,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If -# **autop** +#### autop Replaces double line-breaks with paragraph elements. @@ -40,7 +40,7 @@ _Returns_ - `string`: Text which has been converted into paragraph tags. -# **removep** +#### removep Replaces `

` tags with two line breaks. "Opposite" of autop(). @@ -62,7 +62,6 @@ _Returns_ - `string`: The content with stripped paragraph tags. -

Code is Poetry.

diff --git a/packages/blob/README.md b/packages/blob/README.md index f49f493d17565..2ae25831b3846 100644 --- a/packages/blob/README.md +++ b/packages/blob/README.md @@ -14,7 +14,7 @@ npm install @wordpress/blob --save -# **createBlobURL** +### createBlobURL Create a blob URL from a file. @@ -26,7 +26,7 @@ _Returns_ - `string`: The blob URL. -# **getBlobByURL** +### getBlobByURL Retrieve a file based on a blob URL. The file must have been created by `createBlobURL` and not removed by `revokeBlobURL`, otherwise it will return @@ -40,7 +40,7 @@ _Returns_ - `File|undefined`: The file for the blob URL. -# **getBlobTypeByURL** +### getBlobTypeByURL Retrieve a blob type based on URL. The file must have been created by `createBlobURL` and not removed by `revokeBlobURL`, otherwise it will return @@ -54,7 +54,7 @@ _Returns_ - `string|undefined`: The blob type. -# **isBlobURL** +### isBlobURL Check whether a url is a blob url. @@ -66,7 +66,7 @@ _Returns_ - `boolean`: Is the url a blob url? -# **revokeBlobURL** +### revokeBlobURL Remove the resource and file cache from memory. @@ -74,7 +74,6 @@ _Parameters_ - _url_ `string`: The blob URL. -

Code is Poetry.

diff --git a/packages/block-directory/README.md b/packages/block-directory/README.md index 26d26bb04ed92..35d58dd5b5e2a 100644 --- a/packages/block-directory/README.md +++ b/packages/block-directory/README.md @@ -28,7 +28,7 @@ The following set of dispatching action creators are available on the object ret -# **addInstalledBlockType** +### addInstalledBlockType Returns an action object used to add a block type to the "newly installed" tracking list. @@ -41,7 +41,7 @@ _Returns_ - `Object`: Action object. -# **clearErrorNotice** +### clearErrorNotice Sets the error notice to empty for specific block. @@ -53,7 +53,7 @@ _Returns_ - `Object`: Action object. -# **fetchDownloadableBlocks** +### fetchDownloadableBlocks Returns an action object used in signalling that the downloadable blocks have been requested and are loading. @@ -66,7 +66,7 @@ _Returns_ - `Object`: Action object. -# **installBlockType** +### installBlockType Action triggered to install a block plugin. @@ -78,7 +78,7 @@ _Returns_ - `boolean`: Whether the block was successfully installed & loaded. -# **receiveDownloadableBlocks** +### receiveDownloadableBlocks Returns an action object used in signalling that the downloadable blocks have been updated. @@ -92,7 +92,7 @@ _Returns_ - `Object`: Action object. -# **removeInstalledBlockType** +### removeInstalledBlockType Returns an action object used to remove a block type from the "newly installed" tracking list. @@ -105,7 +105,7 @@ _Returns_ - `Object`: Action object. -# **setErrorNotice** +### setErrorNotice Sets an error notice to be displayed to the user for a given block. @@ -119,20 +119,20 @@ _Returns_ - `Object`: Action object. -# **setIsInstalling** +### setIsInstalling Returns an action object used to indicate install in progress. _Parameters_ -- _blockId_ `string`: -- _isInstalling_ `boolean`: +- _blockId_ `string`: +- _isInstalling_ `boolean`: _Returns_ - `Object`: Action object. -# **uninstallBlockType** +### uninstallBlockType Action triggered to uninstall a block plugin. @@ -148,7 +148,7 @@ The following selectors are available on the object returned by `wp.data.select( -# **getDownloadableBlocks** +### getDownloadableBlocks Returns the available uninstalled blocks. @@ -161,7 +161,7 @@ _Returns_ - `Array`: Downloadable blocks. -# **getErrorNoticeForBlock** +### getErrorNoticeForBlock Returns the error notice for a given block. @@ -174,7 +174,7 @@ _Returns_ - `string|boolean`: The error text, or false if no error. -# **getErrorNotices** +### getErrorNotices Returns all block error notices. @@ -186,7 +186,7 @@ _Returns_ - `Object`: Object with error notices. -# **getInstalledBlockTypes** +### getInstalledBlockTypes Returns the block types that have been installed on the server in this session. @@ -199,7 +199,7 @@ _Returns_ - `Array`: Block type items -# **getNewBlockTypes** +### getNewBlockTypes Returns block types that have been installed on the server and used in the current post. @@ -212,7 +212,7 @@ _Returns_ - `Array`: Block type items. -# **getUnusedBlockTypes** +### getUnusedBlockTypes Returns the block types that have been installed on the server but are not used in the current post. @@ -225,7 +225,7 @@ _Returns_ - `Array`: Block type items. -# **isInstalling** +### isInstalling Returns true if a block plugin install is in progress. @@ -238,7 +238,7 @@ _Returns_ - `boolean`: Whether this block is currently being installed. -# **isRequestingDownloadableBlocks** +### isRequestingDownloadableBlocks Returns true if application is requesting for downloadable blocks. @@ -251,7 +251,6 @@ _Returns_ - `boolean`: Whether a request is in progress for the blocks list. -

Code is Poetry.

diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index b4eb9c473ceb5..552ddfbcba941 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -78,29 +78,29 @@ registerCoreBlocks(); -# **AlignmentControl** +### AlignmentControl Undocumented declaration. -# **AlignmentToolbar** +### AlignmentToolbar Undocumented declaration. -# **Autocomplete** +### Autocomplete _Related_ - -# **BlockAlignmentControl** +### BlockAlignmentControl Undocumented declaration. -# **BlockAlignmentToolbar** +### BlockAlignmentToolbar Undocumented declaration. -# **BlockBreadcrumb** +### BlockBreadcrumb Block breadcrumb component, displaying the hierarchy of the current block selection as a breadcrumb. @@ -113,11 +113,11 @@ _Returns_ - `WPElement`: Block Breadcrumb. -# **BlockColorsStyleSelector** +### BlockColorsStyleSelector Undocumented declaration. -# **BlockContextProvider** +### BlockContextProvider Component which merges passed value with current consumed block context. @@ -127,49 +127,49 @@ _Related_ _Parameters_ -- _props_ `BlockContextProviderProps`: +- _props_ `BlockContextProviderProps`: -# **BlockControls** +### BlockControls Undocumented declaration. -# **BlockEdit** +### BlockEdit Undocumented declaration. -# **BlockEditorKeyboardShortcuts** +### BlockEditorKeyboardShortcuts Undocumented declaration. -# **BlockEditorProvider** +### BlockEditorProvider Undocumented declaration. -# **BlockFormatControls** +### BlockFormatControls Undocumented declaration. -# **BlockIcon** +### BlockIcon Undocumented declaration. -# **BlockInspector** +### BlockInspector Undocumented declaration. -# **BlockList** +### BlockList Undocumented declaration. -# **BlockMover** +### BlockMover Undocumented declaration. -# **BlockNavigationDropdown** +### BlockNavigationDropdown Undocumented declaration. -# **BlockPreview** +### BlockPreview BlockPreview renders a preview of a block or array of blocks. @@ -187,15 +187,15 @@ _Returns_ - `WPComponent`: The component to be rendered. -# **BlockSelectionClearer** +### BlockSelectionClearer Undocumented declaration. -# **BlockSettingsMenu** +### BlockSettingsMenu Undocumented declaration. -# **BlockSettingsMenuControls** +### BlockSettingsMenuControls _Related_ @@ -209,7 +209,7 @@ _Returns_ - `WPElement`: Element. -# **BlockTitle** +### BlockTitle Renders the block's configured title as a string, or empty if the title cannot be determined. @@ -222,18 +222,18 @@ _Usage_ _Parameters_ -- _props_ `Object`: +- _props_ `Object`: - _props.clientId_ `string`: Client ID of block. _Returns_ - `?string`: Block title. -# **BlockToolbar** +### BlockToolbar Undocumented declaration. -# **BlockTools** +### BlockTools Renders block tools (the block toolbar, select/navigation mode toolbar, the insertion point and a slot for the inline rich text toolbar). Must be wrapped @@ -245,43 +245,43 @@ _Parameters_ - _$0.children_ `Object`: The block content and style container. - _$0.\_\_unstableContentRef_ `Object`: Ref holding the content scroll container. -# **BlockVerticalAlignmentControl** +### BlockVerticalAlignmentControl Undocumented declaration. -# **BlockVerticalAlignmentToolbar** +### BlockVerticalAlignmentToolbar Undocumented declaration. -# **ButtonBlockAppender** +### ButtonBlockAppender _Related_ - -# **ButtonBlockerAppender** +### ButtonBlockerAppender -> **Deprecated** +> **Deprecated** Use `ButtonBlockAppender` instead. -# **ColorPalette** +### ColorPalette Undocumented declaration. -# **ColorPaletteControl** +### ColorPaletteControl Undocumented declaration. -# **ContrastChecker** +### ContrastChecker Undocumented declaration. -# **CopyHandler** +### CopyHandler Undocumented declaration. -# **createCustomColorsHOC** +### createCustomColorsHOC A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic for class generation color value, retrieval and color attribute setting. @@ -291,12 +291,15 @@ Use this higher-order component to work with a custom set of colors. _Usage_ ```jsx -const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ]; +const CUSTOM_COLORS = [ + { name: 'Red', slug: 'red', color: '#ff0000' }, + { name: 'Blue', slug: 'blue', color: '#0000ff' }, +]; const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS ); // ... export default compose( - withCustomColors( 'backgroundColor', 'borderColor' ), - MyColorfulComponent, + withCustomColors( 'backgroundColor', 'borderColor' ), + MyColorfulComponent ); ``` @@ -308,15 +311,15 @@ _Returns_ - `Function`: Higher-order component. -# **DefaultBlockAppender** +### DefaultBlockAppender Undocumented declaration. -# **FontSizePicker** +### FontSizePicker Undocumented declaration. -# **getColorClassName** +### getColorClassName Returns a class based on the context a color is being used and its slug. @@ -329,7 +332,7 @@ _Returns_ - `?string`: String with the class corresponding to the color in the provided context. Returns undefined if either colorContextName or colorSlug are not provided. -# **getColorObjectByAttributeValues** +### getColorObjectByAttributeValues Provided an array of color objects as set by the theme or by the editor defaults, and the values of the defined color or custom color returns a color object describing the color. @@ -344,7 +347,7 @@ _Returns_ - `?Object`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined. -# **getColorObjectByColorValue** +### getColorObjectByColorValue Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined. @@ -357,10 +360,10 @@ _Returns_ - `?Object`: Color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement. -# **getFontSize** +### getFontSize - Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. - If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. +Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. +If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. _Parameters_ @@ -372,7 +375,7 @@ _Returns_ - `?Object`: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned. -# **getFontSizeClass** +### getFontSizeClass Returns a class based on fontSizeName. @@ -384,7 +387,7 @@ _Returns_ - `string`: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'. -# **getFontSizeObjectByValue** +### getFontSizeObjectByValue Returns the corresponding font size object for a given value. @@ -397,7 +400,7 @@ _Returns_ - `Object`: Font size object. -# **getGradientSlugByValue** +### getGradientSlugByValue Retrieves the gradient slug per slug. @@ -410,7 +413,7 @@ _Returns_ - `string`: Gradient slug. -# **getGradientValueBySlug** +### getGradientValueBySlug Retrieves the gradient value per slug. @@ -423,108 +426,108 @@ _Returns_ - `string`: Gradient value. -# **InnerBlocks** +### InnerBlocks _Related_ - -# **Inserter** +### Inserter Undocumented declaration. -# **InspectorAdvancedControls** +### InspectorAdvancedControls _Related_ - -# **InspectorControls** +### InspectorControls _Related_ - -# **JustifyContentControl** +### JustifyContentControl Undocumented declaration. -# **JustifyToolbar** +### JustifyToolbar Undocumented declaration. -# **LineHeightControl** +### LineHeightControl Undocumented declaration. -# **MediaPlaceholder** +### MediaPlaceholder _Related_ - -# **MediaReplaceFlow** +### MediaReplaceFlow Undocumented declaration. -# **MediaUpload** +### MediaUpload _Related_ - -# **MediaUploadCheck** +### MediaUploadCheck _Related_ - -# **MultiSelectScrollIntoView** +### MultiSelectScrollIntoView -> **Deprecated** +> **Deprecated** Scrolls the multi block selection end into view if not in view already. This is important to do after selection by keyboard. -# **NavigableToolbar** +### NavigableToolbar Undocumented declaration. -# **ObserveTyping** +### ObserveTyping _Related_ - -# **PanelColorSettings** +### PanelColorSettings Undocumented declaration. -# **PlainText** +### PlainText _Related_ - -# **PreserveScrollInReorder** +### PreserveScrollInReorder Undocumented declaration. -# **RichText** +### RichText _Related_ - -# **RichTextShortcut** +### RichTextShortcut Undocumented declaration. -# **RichTextToolbarButton** +### RichTextToolbarButton Undocumented declaration. -# **SETTINGS_DEFAULTS** +### SETTINGS_DEFAULTS The default editor settings @@ -552,11 +555,11 @@ _Properties_ - _\_\_experimentalBlockPatterns_ `Array`: Array of objects representing the block patterns - _\_\_experimentalBlockPatternCategories_ `Array`: Array of objects representing the block pattern categories -# **SkipToSelectedBlock** +### SkipToSelectedBlock Undocumented declaration. -# **store** +### store Store definition for the block editor namespace. @@ -568,7 +571,7 @@ _Type_ - `Object` -# **storeConfig** +### storeConfig Block editor data store configuration. @@ -580,11 +583,11 @@ _Type_ - `Object` -# **ToolSelector** +### ToolSelector Undocumented declaration. -# **transformStyles** +### transformStyles Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed. @@ -597,31 +600,31 @@ _Returns_ - `Array`: converted rules. -# **Typewriter** +### Typewriter Ensures that the text selection keeps the same vertical distance from the viewport during keyboard events within this component. The vertical distance can vary. It is the last clicked or scrolled to position. -# **URLInput** +### URLInput _Related_ - -# **URLInputButton** +### URLInputButton _Related_ - -# **URLPopover** +### URLPopover _Related_ - -# **useBlockDisplayInformation** +### useBlockDisplayInformation Hook used to try to find a matching block variation and return the appropriate information for display reasons. In order to @@ -641,11 +644,11 @@ _Returns_ - `?WPBlockDisplayInformation`: Block's display information, or `null` when the block or its type not found. -# **useBlockEditContext** +### useBlockEditContext Undocumented declaration. -# **useBlockProps** +### useBlockProps This hook is used to lightly mark an element as a block element. The element should be the outermost element of a block. Call this hook and pass the @@ -659,13 +662,13 @@ _Parameters_ - _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined. - _options_ `Object`: Options for internal use only. -- _options.\_\_unstableIsHtml_ `boolean`: +- _options.\_\_unstableIsHtml_ `boolean`: _Returns_ - `Object`: Props to pass to the element to mark as a block. -# **useSetting** +### useSetting Hook that retrieves the editor setting. It works with nested objects using by finding the value at path. @@ -684,7 +687,7 @@ _Returns_ - `any`: Returns the value defined for the setting. -# **validateThemeColors** +### validateThemeColors Given an array of theme colors checks colors for validity @@ -696,7 +699,7 @@ _Returns_ - `Array`: The array of valid theme colors or the default colors -# **validateThemeGradients** +### validateThemeGradients Given an array of theme gradients checks gradients for validity @@ -708,17 +711,17 @@ _Returns_ - `Array`: The array of valid theme gradients or the default gradients -# **Warning** +### Warning _Related_ - -# **withColorContext** +### withColorContext Undocumented declaration. -# **withColors** +### withColors A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting. @@ -728,8 +731,8 @@ _Usage_ ```jsx export default compose( - withColors( 'backgroundColor', { textColor: 'color' } ), - MyColorfulComponent, + withColors( 'backgroundColor', { textColor: 'color' } ), + MyColorfulComponent ); ``` @@ -741,7 +744,7 @@ _Returns_ - `Function`: Higher-order component. -# **withFontSizes** +### withFontSizes Higher-order component, which handles font size logic for class generation, font size value retrieval, and font size change handling. @@ -754,7 +757,7 @@ _Returns_ - `Function`: Higher-order component. -# **WritingFlow** +### WritingFlow Handles selection and navigation across blocks. This component should be wrapped around BlockList. @@ -764,7 +767,6 @@ _Parameters_ - _props_ `Object`: Component properties. - _props.children_ `WPElement`: Children to be rendered. -

Code is Poetry.

diff --git a/packages/block-editor/src/components/block-list-appender/style.scss b/packages/block-editor/src/components/block-list-appender/style.scss index 5079df7cdadbe..14c9301de6df1 100644 --- a/packages/block-editor/src/components/block-list-appender/style.scss +++ b/packages/block-editor/src/components/block-list-appender/style.scss @@ -14,10 +14,9 @@ margin: $grid-unit-10 0; } - // Add an explicit left margin of zero and auto right margin to work in horizontal - // flex containers. Without it, a "space-between"-like effect from two auto margins - // will cause the black plus to sit in the center of what space is left. - margin: 0 auto 0 0; + // Add a uniform margin around the block. + // This can hopefully avoid havoc in flex containers. + margin: $grid-unit-10; // Black square plus appender. .block-list-appender__toggle { diff --git a/packages/block-editor/src/components/block-list/head.js b/packages/block-editor/src/components/block-list/head.js new file mode 100644 index 0000000000000..9f1ce76320352 --- /dev/null +++ b/packages/block-editor/src/components/block-list/head.js @@ -0,0 +1,18 @@ +/** + * WordPress dependencies + */ +import { createContext, useState } from '@wordpress/element'; + +const context = createContext(); + +export function Head( { children } ) { + const [ element, setElement ] = useState(); + return ( + +
+ { children } + + ); +} + +Head.context = context; diff --git a/packages/block-editor/src/components/block-list/index.js b/packages/block-editor/src/components/block-list/index.js index 46e5d56f9f031..d393c31c8d41a 100644 --- a/packages/block-editor/src/components/block-list/index.js +++ b/packages/block-editor/src/components/block-list/index.js @@ -22,6 +22,7 @@ import { usePreParsePatterns } from '../../utils/pre-parse-patterns'; import { LayoutProvider, defaultLayout } from './layout'; import BlockToolsBackCompat from '../block-tools/back-compat'; import { useBlockSelectionClearer } from '../block-selection-clearer'; +import { Head } from './head'; export const IntersectionObserver = createContext(); @@ -42,24 +43,26 @@ function Root( { className, children } ) { [] ); return ( -
- { children } -
+ +
+ { children } +
+ ); } diff --git a/packages/block-editor/src/components/writing-flow/use-select-all.js b/packages/block-editor/src/components/writing-flow/use-select-all.js index b708d198c2966..3e172d2aa2ee4 100644 --- a/packages/block-editor/src/components/writing-flow/use-select-all.js +++ b/packages/block-editor/src/components/writing-flow/use-select-all.js @@ -31,15 +31,11 @@ export default function useSelectAll() { return; } - const selectedClientIds = getSelectedBlockClientIds(); - - if ( - selectedClientIds.length === 1 && - ! isEntirelySelected( event.target ) - ) { + if ( ! isEntirelySelected( event.target ) ) { return; } + const selectedClientIds = getSelectedBlockClientIds(); const [ firstSelectedClientId ] = selectedClientIds; const rootClientId = getBlockRootClientId( firstSelectedClientId ); let blockClientIds = getBlockOrder( rootClientId ); diff --git a/packages/block-editor/src/hooks/duotone.js b/packages/block-editor/src/hooks/duotone.js index 3cb05246306b5..33d468a30b749 100644 --- a/packages/block-editor/src/hooks/duotone.js +++ b/packages/block-editor/src/hooks/duotone.js @@ -11,6 +11,7 @@ import { getBlockSupport, hasBlockSupport } from '@wordpress/blocks'; import { SVG } from '@wordpress/components'; import { createHigherOrderComponent, useInstanceId } from '@wordpress/compose'; import { addFilter } from '@wordpress/hooks'; +import { useContext, createPortal } from '@wordpress/element'; /** * Internal dependencies @@ -20,6 +21,7 @@ import { __experimentalDuotoneControl as DuotoneControl, useSetting, } from '../components'; +import { Head } from '../components/block-list/head'; const EMPTY_ARRAY = []; @@ -236,13 +238,19 @@ const withDuotoneStyles = createHigherOrderComponent( const className = classnames( props?.className, id ); + const element = useContext( Head.context ); + return ( <> - + { element && + createPortal( + , + element + ) } ); diff --git a/packages/block-editor/src/hooks/layout.js b/packages/block-editor/src/hooks/layout.js index 95f9bdd77dede..15aea3f25580c 100644 --- a/packages/block-editor/src/hooks/layout.js +++ b/packages/block-editor/src/hooks/layout.js @@ -20,6 +20,7 @@ import { } from '@wordpress/components'; import { __ } from '@wordpress/i18n'; import { Icon, positionCenter, stretchWide } from '@wordpress/icons'; +import { useContext, createPortal } from '@wordpress/element'; /** * Internal dependencies @@ -28,6 +29,7 @@ import { store as blockEditorStore } from '../store'; import { InspectorControls } from '../components'; import useSetting from '../components/use-setting'; import { LayoutStyle } from '../components/block-list/layout'; +import { Head } from '../components/block-list/head'; function LayoutPanel( { setAttributes, attributes } ) { const { layout = {} } = attributes; @@ -207,12 +209,18 @@ export const withLayoutStyles = createHigherOrderComponent( `wp-container-${ id }` ); + const element = useContext( Head.context ); + return ( <> - + { element && + createPortal( + , + element + ) } ); diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 84f86a88a5b74..c10c1a44b27bb 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -72,7 +72,7 @@ apply_filter( 'render_block', 'render_block_my_block' ); -# **registerCoreBlocks** +### registerCoreBlocks Function to register core blocks provided by the block editor. @@ -88,7 +88,6 @@ _Parameters_ - _blocks_ `Array`: An optional array of the core blocks being registered. -

Code is Poetry.

diff --git a/packages/block-library/src/button/edit.js b/packages/block-library/src/button/edit.js index 3f36a56427239..6cd15639617ca 100644 --- a/packages/block-library/src/button/edit.js +++ b/packages/block-library/src/button/edit.js @@ -7,7 +7,7 @@ import classnames from 'classnames'; * WordPress dependencies */ import { __ } from '@wordpress/i18n'; -import { useCallback, useState, useRef } from '@wordpress/element'; +import { useCallback, useEffect, useState, useRef } from '@wordpress/element'; import { Button, ButtonGroup, @@ -68,27 +68,42 @@ function URLPicker( { opensInNewTab, onToggleOpenInNewTab, anchorRef, + richTextRef, } ) { - const [ isURLPickerOpen, setIsURLPickerOpen ] = useState( false ); - const urlIsSet = !! url; - const urlIsSetandSelected = urlIsSet && isSelected; - const openLinkControl = () => { - setIsURLPickerOpen( true ); - return false; // prevents default behaviour for event + const [ isEditingURL, setIsEditingURL ] = useState( false ); + const isURLSet = !! url; + + const startEditing = ( event ) => { + event.preventDefault(); + setIsEditingURL( true ); }; - const unlinkButton = () => { + + const unlink = () => { setAttributes( { url: undefined, linkTarget: undefined, rel: undefined, } ); - setIsURLPickerOpen( false ); + setIsEditingURL( false ); }; - const linkControl = ( isURLPickerOpen || urlIsSetandSelected ) && ( + + useEffect( () => { + if ( ! isSelected ) { + setIsEditingURL( false ); + } + }, [ isSelected ] ); + + const isLinkControlVisible = isSelected && ( isEditingURL || isURLSet ); + + const linkControl = isLinkControlVisible && ( setIsURLPickerOpen( false ) } + onClose={ () => { + setIsEditingURL( false ); + richTextRef.current?.focus(); + } } anchorRef={ anchorRef?.current } + focusOnMount={ isEditingURL ? 'firstElement' : false } > { + unlink(); + richTextRef.current?.focus(); + } } + forceIsEditingLink={ isEditingURL } /> ); + return ( <> - { ! urlIsSet && ( + { ! isURLSet && ( ) } - { urlIsSetandSelected && ( + { isURLSet && ( ) } @@ -133,8 +154,11 @@ function URLPicker( { { + unlink(); + richTextRef.current?.focus(); + }, } } /> ) } @@ -195,6 +219,7 @@ function ButtonEdit( props ) { const borderRadius = style?.border?.radius; const colorProps = useColorProps( attributes ); const ref = useRef(); + const richTextRef = useRef(); const blockProps = useBlockProps( { ref } ); return ( @@ -207,6 +232,7 @@ function ButtonEdit( props ) { } ) } > -# **parse** +### parse Parser function, that converts input HTML into a block based structure. @@ -26,21 +26,27 @@ Input post: ```html -
-
-

Left

-
- - - -
-

Middle

-
- - - -
-
+
+ +
+ +

Left

+ +
+ + + +
+ +

Middle

+ +
+ + + +
+ +
``` @@ -49,49 +55,51 @@ Parsing code: ```js import { parse } from '@wordpress/block-serialization-default-parser'; -parse( post ) === [ - { - blockName: "core/columns", - attrs: { - columns: 3 - }, - innerBlocks: [ - { - blockName: "core/column", - attrs: null, - innerBlocks: [ - { - blockName: "core/paragraph", - attrs: null, - innerBlocks: [], - innerHTML: "\n

Left

\n" - } - ], - innerHTML: '\n
\n' - }, - { - blockName: "core/column", - attrs: null, - innerBlocks: [ - { - blockName: "core/paragraph", - attrs: null, - innerBlocks: [], - innerHTML: "\n

Middle

\n" - } - ], - innerHTML: '\n
\n' - }, - { - blockName: "core/column", - attrs: null, - innerBlocks: [], - innerHTML: '\n
\n' - } - ], - innerHTML: '\n
\n\n\n\n
\n' - } -]; +parse( post ) === + [ + { + blockName: 'core/columns', + attrs: { + columns: 3, + }, + innerBlocks: [ + { + blockName: 'core/column', + attrs: null, + innerBlocks: [ + { + blockName: 'core/paragraph', + attrs: null, + innerBlocks: [], + innerHTML: '\n

Left

\n', + }, + ], + innerHTML: '\n
\n', + }, + { + blockName: 'core/column', + attrs: null, + innerBlocks: [ + { + blockName: 'core/paragraph', + attrs: null, + innerBlocks: [], + innerHTML: '\n

Middle

\n', + }, + ], + innerHTML: '\n
\n', + }, + { + blockName: 'core/column', + attrs: null, + innerBlocks: [], + innerHTML: '\n
\n', + }, + ], + innerHTML: + '\n
\n\n\n\n
\n', + }, + ]; ``` _Parameters_ @@ -102,7 +110,6 @@ _Returns_ - `Array`: A block-based representation of the input HTML. - ## Theory diff --git a/packages/blocks/README.md b/packages/blocks/README.md index dd51909dedfd4..7bdca8b1a3296 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -183,7 +183,7 @@ In the random image block above, we've given the `alt` attribute of the image a -# **cloneBlock** +### cloneBlock Given a block object, returns a copy of the block object, optionally merging new attributes and/or replacing its inner blocks. @@ -198,7 +198,7 @@ _Returns_ - `Object`: A cloned block. -# **createBlock** +### createBlock Returns a block object given its type and attributes. @@ -212,7 +212,7 @@ _Returns_ - `Object`: Block object. -# **createBlocksFromInnerBlocksTemplate** +### createBlocksFromInnerBlocksTemplate Given an array of InnerBlocks templates or Block Objects, returns an array of created Blocks from them. @@ -227,7 +227,7 @@ _Returns_ - `Object[]`: Array of Block objects. -# **doBlocksMatchTemplate** +### doBlocksMatchTemplate Checks whether a list of blocks matches a template by comparing the block names. @@ -240,7 +240,7 @@ _Returns_ - `boolean`: Whether the list of blocks matches a templates -# **findTransform** +### findTransform Given an array of transforms, returns the highest-priority transform where the predicate function returns a truthy value. A higher-priority transform @@ -257,7 +257,7 @@ _Returns_ - `?Object`: Highest-priority transform candidate. -# **getBlockAttributes** +### getBlockAttributes Returns the block attributes of a registered block node given its type. @@ -271,7 +271,7 @@ _Returns_ - `Object`: All block attributes. -# **getBlockContent** +### getBlockContent Given a block object, returns the Block's Inner HTML markup. @@ -283,7 +283,7 @@ _Returns_ - `string`: HTML. -# **getBlockDefaultClassName** +### getBlockDefaultClassName Returns the block's default classname from its name. @@ -295,20 +295,20 @@ _Returns_ - `string`: The block's default class. -# **getBlockFromExample** +### getBlockFromExample Create a block object from the example API. _Parameters_ -- _name_ `string`: -- _example_ `Object`: +- _name_ `string`: +- _example_ `Object`: _Returns_ - `Object`: block. -# **getBlockMenuDefaultClassName** +### getBlockMenuDefaultClassName Returns the block's default menu item classname from its name. @@ -320,7 +320,7 @@ _Returns_ - `string`: The block's default menu item class. -# **getBlockSupport** +### getBlockSupport Returns the block support value for a feature, if defined. @@ -334,7 +334,7 @@ _Returns_ - `?*`: Block support value -# **getBlockTransforms** +### getBlockTransforms Returns normal block transforms for a given transform direction, optionally for a specific block by name, or an empty array if there are no transforms. @@ -350,7 +350,7 @@ _Returns_ - `Array`: Block transforms for direction. -# **getBlockType** +### getBlockType Returns a registered block type. @@ -362,7 +362,7 @@ _Returns_ - `?Object`: Block type. -# **getBlockTypes** +### getBlockTypes Returns all registered blocks. @@ -370,7 +370,7 @@ _Returns_ - `Array`: Block settings. -# **getBlockVariations** +### getBlockVariations Returns an array with the variations of a given block type. @@ -383,7 +383,7 @@ _Returns_ - `(WPBlockVariation[]|void)`: Block variations. -# **getCategories** +### getCategories Returns all the block categories. @@ -391,7 +391,7 @@ _Returns_ - `WPBlockCategory[]`: Block categories. -# **getChildBlockNames** +### getChildBlockNames Returns an array with the child blocks of a given block. @@ -403,7 +403,7 @@ _Returns_ - `Array`: Array of child block names. -# **getDefaultBlockName** +### getDefaultBlockName Retrieves the default block name. @@ -411,7 +411,7 @@ _Returns_ - `?string`: Block name. -# **getFreeformContentHandlerName** +### getFreeformContentHandlerName Retrieves name of block handling non-block content, or undefined if no handler has been defined. @@ -420,7 +420,7 @@ _Returns_ - `?string`: Block name. -# **getGroupingBlockName** +### getGroupingBlockName Retrieves name of block used for handling grouping interactions. @@ -428,11 +428,11 @@ _Returns_ - `?string`: Block name. -# **getPhrasingContentSchema** +### getPhrasingContentSchema Undocumented declaration. -# **getPossibleBlockTransformations** +### getPossibleBlockTransformations Returns an array of block types that the set of blocks received as argument can be transformed into. @@ -445,7 +445,7 @@ _Returns_ - `Array`: Block types that the blocks argument can be transformed to. -# **getSaveContent** +### getSaveContent Given a block type containing a save render implementation and attributes, returns the static markup to be saved. @@ -460,7 +460,7 @@ _Returns_ - `string`: Save content. -# **getSaveElement** +### getSaveElement Given a block type containing a save render implementation and attributes, returns the enhanced element to be saved or string when raw HTML expected. @@ -475,7 +475,7 @@ _Returns_ - `Object|string`: Save element or raw HTML string. -# **getUnregisteredTypeHandlerName** +### getUnregisteredTypeHandlerName Retrieves name of block handling unregistered block types, or undefined if no handler has been defined. @@ -484,7 +484,7 @@ _Returns_ - `?string`: Block name. -# **hasBlockSupport** +### hasBlockSupport Returns true if the block defines support for a feature, or false otherwise. @@ -498,7 +498,7 @@ _Returns_ - `boolean`: Whether block supports feature. -# **hasChildBlocks** +### hasChildBlocks Returns a boolean indicating if a block has child blocks or not. @@ -510,7 +510,7 @@ _Returns_ - `boolean`: True if a block contains child blocks and false otherwise. -# **hasChildBlocksWithInserterSupport** +### hasChildBlocksWithInserterSupport Returns a boolean indicating if a block has at least one child block with inserter support. @@ -522,7 +522,7 @@ _Returns_ - `boolean`: True if a block contains at least one child blocks with inserter support and false otherwise. -# **isReusableBlock** +### isReusableBlock Determines whether or not the given block is a reusable block. This is a special block type that is used to point to a global block stored via the @@ -536,7 +536,7 @@ _Returns_ - `boolean`: Whether the given block is a reusable block. -# **isTemplatePart** +### isTemplatePart Determines whether or not the given block is a template part. This is a special block type that allows composing a page template out of reusable @@ -550,7 +550,7 @@ _Returns_ - `boolean`: Whether the given block is a template part. -# **isUnmodifiedDefaultBlock** +### isUnmodifiedDefaultBlock Determines whether the block is a default block and its attributes are equal to the default attributes @@ -564,7 +564,7 @@ _Returns_ - `boolean`: Whether the block is an unmodified default block -# **isValidBlockContent** +### isValidBlockContent Returns true if the parsed block is valid given the input content. A block is considered valid if, when serialized with assumed attributes, the content @@ -582,7 +582,7 @@ _Returns_ - `boolean`: Whether block is valid. -# **isValidIcon** +### isValidIcon Function that checks if the parameter is a valid icon. @@ -594,7 +594,7 @@ _Returns_ - `boolean`: True if the parameter is a valid icon and false otherwise. -# **normalizeIconObject** +### normalizeIconObject Function that receives an icon as set by the blocks during the registration and returns a new icon object that is normalized so we can rely on just on possible icon structure @@ -608,7 +608,7 @@ _Returns_ - `WPBlockTypeIconDescriptor`: Object describing the icon. -# **parse** +### parse Utilizes an optimized token-driven parser based on the Gutenberg grammar spec defined through a parsing expression grammar to take advantage of the regular @@ -634,7 +634,7 @@ _Returns_ - `Array`: Block list. -# **parseWithAttributeSchema** +### parseWithAttributeSchema Given a block's raw content and an attribute's schema returns the attribute's value depending on its source. @@ -648,13 +648,13 @@ _Returns_ - `*`: Attribute value. -# **pasteHandler** +### pasteHandler Converts an HTML string to known blocks. Strips everything else. _Parameters_ -- _options_ `Object`: +- _options_ `Object`: - _options.HTML_ `[string]`: The HTML to convert. - _options.plainText_ `[string]`: Plain text version. - _options.mode_ `[string]`: Handle content as blocks or inline content. _ 'AUTO': Decide based on the content passed. _ 'INLINE': Always handle as inline content, and return string. \* 'BLOCKS': Always handle as blocks, and return array of blocks. @@ -665,20 +665,20 @@ _Returns_ - `Array|string`: A list of blocks or a string, depending on `handlerMode`. -# **rawHandler** +### rawHandler Converts an HTML string to known blocks. _Parameters_ -- _$1_ `Object`: +- _$1_ `Object`: - _$1.HTML_ `string`: The HTML to convert. _Returns_ - `Array`: A list of blocks. -# **registerBlockCollection** +### registerBlockCollection Registers a new block collection to group blocks in the same namespace in the inserter. @@ -689,7 +689,7 @@ _Parameters_ - _settings.title_ `string`: The title to display in the block inserter. - _settings.icon_ `[Object]`: The icon to display in the block inserter. -# **registerBlockStyle** +### registerBlockStyle Registers a new block style variation for the given block. @@ -698,7 +698,7 @@ _Parameters_ - _blockName_ `string`: Name of block (example: “core/latest-posts”). - _styleVariation_ `Object`: Object containing `name` which is the class name applied to the block and `label` which identifies the variation to the user. -# **registerBlockType** +### registerBlockType Registers a new block provided a unique name and an object defining its behavior. Once registered, the block is made available as an option to any @@ -713,7 +713,7 @@ _Returns_ - `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. -# **registerBlockTypeFromMetadata** +### registerBlockTypeFromMetadata > **Deprecated** Use `registerBlockType` instead. @@ -728,7 +728,7 @@ _Returns_ - `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. -# **registerBlockVariation** +### registerBlockVariation Registers a new block variation for the given block type. @@ -737,7 +737,7 @@ _Parameters_ - _blockName_ `string`: Name of the block (example: “core/columns”). - _variation_ `WPBlockVariation`: Object describing a block variation. -# **serialize** +### serialize Takes a block or set of blocks and returns the serialized post content. @@ -750,7 +750,7 @@ _Returns_ - `string`: The post content. -# **setCategories** +### setCategories Sets the block categories. @@ -758,7 +758,7 @@ _Parameters_ - _categories_ `WPBlockCategory[]`: Block categories. -# **setDefaultBlockName** +### setDefaultBlockName Assigns the default block name. @@ -766,7 +766,7 @@ _Parameters_ - _name_ `string`: Block name. -# **setFreeformContentHandlerName** +### setFreeformContentHandlerName Assigns name of block for handling non-block content. @@ -774,7 +774,7 @@ _Parameters_ - _blockName_ `string`: Block name. -# **setGroupingBlockName** +### setGroupingBlockName Assigns name of block for handling block grouping interactions. @@ -782,7 +782,7 @@ _Parameters_ - _name_ `string`: Block name. -# **setUnregisteredTypeHandlerName** +### setUnregisteredTypeHandlerName Assigns name of block handling unregistered block types. @@ -790,7 +790,7 @@ _Parameters_ - _blockName_ `string`: Block name. -# **store** +### store Store definition for the blocks namespace. @@ -802,7 +802,7 @@ _Type_ - `Object` -# **switchToBlockType** +### switchToBlockType Switch one or more blocks into one or more blocks of the new block type. @@ -815,7 +815,7 @@ _Returns_ - `?Array`: Array of blocks or null. -# **synchronizeBlocksWithTemplate** +### synchronizeBlocksWithTemplate Synchronize a block list with a block template. @@ -833,7 +833,7 @@ _Returns_ - `Array`: Updated Block list. -# **unregisterBlockStyle** +### unregisterBlockStyle Unregisters a block style variation for the given block. @@ -842,7 +842,7 @@ _Parameters_ - _blockName_ `string`: Name of block (example: “core/latest-posts”). - _styleVariationName_ `string`: Name of class applied to the block. -# **unregisterBlockType** +### unregisterBlockType Unregisters a block. @@ -854,7 +854,7 @@ _Returns_ - `?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. -# **unregisterBlockVariation** +### unregisterBlockVariation Unregisters a block variation defined for the given block type. @@ -863,7 +863,7 @@ _Parameters_ - _blockName_ `string`: Name of the block (example: “core/columns”). - _variationName_ `string`: Name of the variation defined for the block. -# **updateCategory** +### updateCategory Updates a category. @@ -872,7 +872,7 @@ _Parameters_ - _slug_ `string`: Block category slug. - _category_ `WPBlockCategory`: Object containing the category properties that should be updated. -# **withBlockContentContext** +### withBlockContentContext A Higher Order Component used to inject BlockContent using context to the wrapped component. @@ -881,7 +881,6 @@ _Returns_ - `WPComponent`: Enhanced component with injected BlockContent as prop. -

Code is Poetry.

diff --git a/packages/components/src/font-size-picker/index.js b/packages/components/src/font-size-picker/index.js index 5a1080c8d8b52..77fadfccd2e70 100644 --- a/packages/components/src/font-size-picker/index.js +++ b/packages/components/src/font-size-picker/index.js @@ -126,10 +126,14 @@ function FontSizePicker( if ( 0 === parseFloat( nextSize ) || ! nextSize ) { onChange( undefined ); } else { - onChange( nextSize ); + onChange( + hasUnits + ? nextSize + : parseInt( nextSize, 10 ) + ); } } } - units={ units } + units={ hasUnits ? units : false } /> ) }
- ); -} + const constrainedTabbingRef = useConstrainedTabbing(); + return ( +
+
+ ); +}; ``` _Returns_ - `Object|Function`: Element Ref. -# **useCopyOnClick** +### useCopyOnClick -> **Deprecated** +> **Deprecated** Copies the text to the clipboard when the element is clicked. @@ -174,7 +176,7 @@ _Returns_ - `boolean`: Whether or not the text has been copied. Resets after the timeout. -# **useCopyToClipboard** +### useCopyToClipboard Copies the given text to the clipboard when the element is clicked. @@ -187,7 +189,7 @@ _Returns_ - `RefObject`: A ref to assign to the target element. -# **useDebounce** +### useDebounce Debounces a function with Lodash's `debounce`. A new debounced function will be returned and any scheduled calls cancelled if any of the arguments change, @@ -202,7 +204,7 @@ _Returns_ - `Function`: Debounced function. -# **useFocusOnMount** +### useFocusOnMount Hook used to focus the first tabbable element on mount. @@ -212,14 +214,14 @@ _Usage_ import { useFocusOnMount } from '@wordpress/compose'; const WithFocusOnMount = () => { - const ref = useFocusOnMount() - return ( -
-
- ); -} + const ref = useFocusOnMount(); + return ( +
+
+ ); +}; ``` _Parameters_ @@ -230,7 +232,7 @@ _Returns_ - `Function`: Ref callback. -# **useFocusReturn** +### useFocusReturn When opening modals/sidebars/dialogs, the focus must move to the opened area and return to the @@ -243,14 +245,14 @@ _Usage_ import { useFocusReturn } from '@wordpress/compose'; const WithFocusReturn = () => { - const ref = useFocusReturn() - return ( -
-
- ); -} + const ref = useFocusReturn(); + return ( +
+
+ ); +}; ``` _Parameters_ @@ -261,7 +263,7 @@ _Returns_ - `Function`: Element Ref. -# **useInstanceId** +### useInstanceId Provides a unique instance ID. @@ -275,13 +277,13 @@ _Returns_ - `string | number`: The unique instance id. -# **useIsomorphicLayoutEffect** +### useIsomorphicLayoutEffect Preferred over direct usage of `useLayoutEffect` when supporting server rendered components (SSR) because currently React throws a warning when using useLayoutEffect in that environment. -# **useKeyboardShortcut** +### useKeyboardShortcut Attach a keyboard shortcut handler. @@ -291,7 +293,7 @@ _Parameters_ - _callback_ `Function`: Shortcut callback. - _options_ `WPKeyboardShortcutConfig`: Shortcut options. -# **useMediaQuery** +### useMediaQuery Runs a media query and returns its value when it changes. @@ -303,7 +305,7 @@ _Returns_ - `boolean`: return value of the media query. -# **useMergeRefs** +### useMergeRefs Merges refs into one ref callback. Ensures the merged ref callbacks are only called when it changes (as a result of a `useCallback` dependency update) or @@ -321,7 +323,7 @@ _Returns_ - `RefCallback`: The merged ref callback. -# **usePrevious** +### usePrevious Use something's value from the previous render. Based on . @@ -334,7 +336,7 @@ _Returns_ - `T|undefined`: The value from the previous render. -# **useReducedMotion** +### useReducedMotion Hook returning whether the user has a preference for reduced motion. @@ -342,7 +344,7 @@ _Returns_ - `boolean`: Reduced motion preference value. -# **useRefEffect** +### useRefEffect Effect-like ref callback. Just like with `useEffect`, this allows you to return a cleanup function to be run if the ref changes or one of the @@ -366,7 +368,7 @@ _Returns_ - `Function`: Ref callback. -# **useResizeObserver** +### useResizeObserver Hook which allows to listen the resize event of any target element when it changes sizes. _Note: `useResizeObserver` will report `null` until after first render_ @@ -390,7 +392,7 @@ _Returns_ - `Array`: An array of {Element} `resizeListener` and {?Object} `sizes` with properties `width` and `height` -# **useThrottle** +### useThrottle Throttles a function with Lodash's `throttle`. A new throttled function will be returned and any scheduled calls cancelled if any of the arguments change, @@ -405,7 +407,7 @@ _Returns_ - `Function`: Throttled function. -# **useViewportMatch** +### useViewportMatch Returns true if the viewport matches the given query, or false otherwise. @@ -425,7 +427,7 @@ _Returns_ - `boolean`: Whether viewport matches query. -# **useWarnOnChange** +### useWarnOnChange Hook that performs a shallow comparison between the preview value of an object and the new one, if there's a difference, it prints it to the console. @@ -434,10 +436,10 @@ this is useful in performance related work, to check why a component re-renders. _Usage_ ```jsx -function MyComponent(props) { - useWarnOnChange(props); +function MyComponent( props ) { + useWarnOnChange( props ); - return "Something"; + return 'Something'; } ``` @@ -446,9 +448,9 @@ _Parameters_ - _object_ `Object`: Object which changes to compare. - _prefix_ `string`: Just a prefix to show when console logging. -# **withGlobalEvents** +### withGlobalEvents -> **Deprecated** +> **Deprecated** Higher-order component creator which, given an object of DOM event types and values corresponding to a callback function name on the component, will @@ -465,7 +467,7 @@ _Returns_ - `Function`: Higher-order component. -# **withInstanceId** +### withInstanceId A Higher Order Component used to be provide a unique instance ID by component. @@ -474,7 +476,7 @@ _Type_ - `PropInjectingHigherOrderComponent< { instanceId: string | number; } >` -# **withSafeTimeout** +### withSafeTimeout A higher-order component used to provide and manage delayed function calls that ought to be bound to a component's lifecycle. @@ -487,7 +489,7 @@ _Returns_ - `WPComponent`: Wrapped component. -# **withState** +### withState A Higher Order Component used to provide and manage internal component state via props. @@ -500,7 +502,6 @@ _Returns_ - `WPComponent`: Wrapped component. -

Code is Poetry.

diff --git a/packages/core-data/README.md b/packages/core-data/README.md index 3c5d3ff07a6b9..ac93d0966542a 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -42,7 +42,7 @@ The following set of dispatching action creators are available on the object ret -# **addEntities** +### addEntities Returns an action object used in adding new entities. @@ -54,7 +54,7 @@ _Returns_ - `Object`: Action object. -# **deleteEntityRecord** +### deleteEntityRecord Action triggered to delete an entity record. @@ -67,7 +67,7 @@ _Parameters_ - _options_ `[Object]`: Delete options. - _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. -# **editEntityRecord** +### editEntityRecord Returns an action object that triggers an edit to an entity record. @@ -85,7 +85,7 @@ _Returns_ - `Object`: Action object. -# **receiveAutosaves** +### receiveAutosaves Returns an action object used in signalling that the autosaves for a post have been received. @@ -99,7 +99,7 @@ _Returns_ - `Object`: Action object. -# **receiveCurrentTheme** +### receiveCurrentTheme Returns an action object used in signalling that the current theme has been received. @@ -111,7 +111,7 @@ _Returns_ - `Object`: Action object. -# **receiveCurrentUser** +### receiveCurrentUser Returns an action used in signalling that the current user has been received. @@ -123,7 +123,7 @@ _Returns_ - `Object`: Action object. -# **receiveEmbedPreview** +### receiveEmbedPreview Returns an action object used in signalling that the preview data for a given URl has been received. @@ -137,7 +137,7 @@ _Returns_ - `Object`: Action object. -# **receiveEntityRecords** +### receiveEntityRecords Returns an action object used in signalling that entity records have been received. @@ -154,7 +154,7 @@ _Returns_ - `Object`: Action object. -# **receiveThemeSupports** +### receiveThemeSupports Returns an action object used in signalling that the index has been received. @@ -166,7 +166,7 @@ _Returns_ - `Object`: Action object. -# **receiveUploadPermissions** +### receiveUploadPermissions Returns an action object used in signalling that Upload permissions have been received. @@ -178,7 +178,7 @@ _Returns_ - `Object`: Action object. -# **receiveUserPermission** +### receiveUserPermission Returns an action object used in signalling that the current user has permission to perform an action on a REST resource. @@ -192,7 +192,7 @@ _Returns_ - `Object`: Action object. -# **receiveUserQuery** +### receiveUserQuery Returns an action object used in signalling that authors have been received. @@ -205,12 +205,12 @@ _Returns_ - `Object`: Action object. -# **redo** +### redo Action triggered to redo the last undoed edit to an entity record, if any. -# **saveEditedEntityRecord** +### saveEditedEntityRecord Action triggered to save an entity record's edits. @@ -221,7 +221,7 @@ _Parameters_ - _recordId_ `Object`: ID of the record. - _options_ `Object`: Saving options. -# **saveEntityRecord** +### saveEntityRecord Action triggered to save an entity record. @@ -234,7 +234,7 @@ _Parameters_ - _options.isAutosave_ `[boolean]`: Whether this is an autosave. - _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. -# **undo** +### undo Action triggered to undo the last edit to an entity record, if any. @@ -247,7 +247,7 @@ The following selectors are available on the object returned by `wp.data.select( -# **canUser** +### canUser Returns whether the current user can perform the given action on the given REST resource. @@ -268,7 +268,7 @@ _Returns_ - `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. -# **canUserEditEntityRecord** +### canUserEditEntityRecord Returns whether the current user can edit the given entity. @@ -288,7 +288,7 @@ _Returns_ - `boolean|undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. -# **getAuthors** +### getAuthors Returns all available authors. @@ -301,7 +301,7 @@ _Returns_ - `Array`: Authors list. -# **getAutosave** +### getAutosave Returns the autosave for the post and author. @@ -316,7 +316,7 @@ _Returns_ - `?Object`: The autosave for the post and author. -# **getAutosaves** +### getAutosaves Returns the latest autosaves for the post. @@ -333,7 +333,7 @@ _Returns_ - `?Array`: An array of autosaves for the post, or undefined if there is none. -# **getCurrentTheme** +### getCurrentTheme Return the current theme. @@ -345,7 +345,7 @@ _Returns_ - `Object`: The current theme. -# **getCurrentUser** +### getCurrentUser Returns the current user. @@ -357,7 +357,7 @@ _Returns_ - `Object`: Current user object. -# **getEditedEntityRecord** +### getEditedEntityRecord Returns the specified entity record, merged with its edits. @@ -372,7 +372,7 @@ _Returns_ - `Object?`: The entity record, merged with its edits. -# **getEmbedPreview** +### getEmbedPreview Returns the embed preview for the given URL. @@ -385,7 +385,7 @@ _Returns_ - `*`: 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. @@ -398,7 +398,7 @@ _Returns_ - `Array`: Array of entities with config matching kind. -# **getEntity** +### getEntity Returns the entity object given its kind and name. @@ -412,7 +412,7 @@ _Returns_ - `Object`: Entity -# **getEntityRecord** +### getEntityRecord Returns the Entity's record object by key. Returns `null` if the value is not yet received, undefined if the value entity is known to not exist, or the @@ -430,7 +430,7 @@ _Returns_ - `Object?`: Record. -# **getEntityRecordEdits** +### getEntityRecordEdits Returns the specified entity record's edits. @@ -445,7 +445,7 @@ _Returns_ - `Object?`: The entity record's edits. -# **getEntityRecordNonTransientEdits** +### getEntityRecordNonTransientEdits Returns the specified entity record's non transient edits. @@ -464,7 +464,7 @@ _Returns_ - `Object?`: The entity record's non transient edits. -# **getEntityRecords** +### getEntityRecords Returns the Entity's records. @@ -479,7 +479,7 @@ _Returns_ - `?Array`: Records. -# **getLastEntityDeleteError** +### getLastEntityDeleteError Returns the specified entity record's last delete error. @@ -494,7 +494,7 @@ _Returns_ - `Object?`: The entity record's save error. -# **getLastEntitySaveError** +### getLastEntitySaveError Returns the specified entity record's last save error. @@ -509,7 +509,7 @@ _Returns_ - `Object?`: The entity record's save error. -# **getRawEntityRecord** +### getRawEntityRecord Returns the entity's record object by key, with its attributes mapped to their raw values. @@ -525,7 +525,7 @@ _Returns_ - `Object?`: Object with the entity's raw attributes. -# **getRedoEdit** +### getRedoEdit Returns the next edit from the current undo offset for the entity records edits history, if any. @@ -538,7 +538,7 @@ _Returns_ - `Object?`: The edit. -# **getReferenceByDistinctEdits** +### 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 @@ -559,7 +559,7 @@ _Returns_ - `*`: A value whose reference will change only when an edit occurs. -# **getThemeSupports** +### getThemeSupports Return theme supports data in the index. @@ -571,7 +571,7 @@ _Returns_ - `*`: Index data. -# **getUndoEdit** +### getUndoEdit Returns the previous edit from the current undo offset for the entity records edits history, if any. @@ -584,7 +584,7 @@ _Returns_ - `Object?`: The edit. -# **getUserQueryResults** +### getUserQueryResults Returns all the users returned by a query ID. @@ -597,7 +597,7 @@ _Returns_ - `Array`: Users list. -# **hasEditsForEntityRecord** +### hasEditsForEntityRecord Returns true if the specified entity record has edits, and false otherwise. @@ -613,7 +613,7 @@ _Returns_ - `boolean`: Whether the entity record has edits or not. -# **hasEntityRecords** +### hasEntityRecords Returns true if records have been received for the given set of parameters, or false otherwise. @@ -629,7 +629,7 @@ _Returns_ - `boolean`: Whether entity records have been received. -# **hasFetchedAutosaves** +### hasFetchedAutosaves Returns true if the REST request for autosaves has completed. @@ -643,7 +643,7 @@ _Returns_ - `boolean`: True if the REST request was completed. False otherwise. -# **hasRedo** +### hasRedo Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise. @@ -656,7 +656,7 @@ _Returns_ - `boolean`: Whether there is a next edit or not. -# **hasUndo** +### hasUndo Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise. @@ -669,7 +669,7 @@ _Returns_ - `boolean`: Whether there is a previous edit or not. -# **isAutosavingEntityRecord** +### isAutosavingEntityRecord Returns true if the specified entity record is autosaving, and false otherwise. @@ -684,7 +684,7 @@ _Returns_ - `boolean`: Whether the entity record is autosaving or not. -# **isDeletingEntityRecord** +### isDeletingEntityRecord Returns true if the specified entity record is deleting, and false otherwise. @@ -699,7 +699,7 @@ _Returns_ - `boolean`: Whether the entity record is deleting or not. -# **isPreviewEmbedFallback** +### isPreviewEmbedFallback Determines if the returned preview is an oEmbed link fallback. @@ -716,7 +716,7 @@ _Returns_ - `boolean`: Is the preview for the URL an oEmbed link fallback. -# **isRequestingEmbedPreview** +### isRequestingEmbedPreview Returns true if a request is in progress for embed preview data, or false otherwise. @@ -730,7 +730,7 @@ _Returns_ - `boolean`: Whether a request is in progress for an embed preview. -# **isSavingEntityRecord** +### isSavingEntityRecord Returns true if the specified entity record is saving, and false otherwise. @@ -745,7 +745,6 @@ _Returns_ - `boolean`: Whether the entity record is saving or not. -

Code is Poetry.

diff --git a/packages/core-data/src/batch/default-processor.js b/packages/core-data/src/batch/default-processor.js index d459923218e12..34f38ff5c3d0d 100644 --- a/packages/core-data/src/batch/default-processor.js +++ b/packages/core-data/src/batch/default-processor.js @@ -1,10 +1,23 @@ +/** + * External dependencies + */ +import { chunk } from 'lodash'; + /** * WordPress dependencies */ import apiFetch from '@wordpress/api-fetch'; /** - * Default batch processor. Sends its input requests to /v1/batch. + * Maximum number of requests to place in a single batch request. Obtained by + * sending a preflight OPTIONS request to /batch/v1/. + * + * @type {number?} + */ +let maxItems = null; + +/** + * Default batch processor. Sends its input requests to /batch/v1. * * @param {Array} requests List of API requests to perform at once. * @@ -13,33 +26,51 @@ import apiFetch from '@wordpress/api-fetch'; * (if not ). */ export default async function defaultProcessor( requests ) { - const batchResponse = await apiFetch( { - path: '/batch/v1', - method: 'POST', - data: { - validation: 'require-all-validate', - requests: requests.map( ( request ) => ( { - path: request.path, - body: request.data, // Rename 'data' to 'body'. - method: request.method, - headers: request.headers, - } ) ), - }, - } ); - - if ( batchResponse.failed ) { - return batchResponse.responses.map( ( response ) => ( { - error: response?.body, - } ) ); + if ( maxItems === null ) { + const preflightResponse = await apiFetch( { + path: '/batch/v1', + method: 'OPTIONS', + } ); + maxItems = preflightResponse.endpoints[ 0 ].args.requests.maxItems; } - return batchResponse.responses.map( ( response ) => { - const result = {}; - if ( response.status >= 200 && response.status < 300 ) { - result.output = response.body; + const results = []; + + for ( const batchRequests of chunk( requests, maxItems ) ) { + const batchResponse = await apiFetch( { + path: '/batch/v1', + method: 'POST', + data: { + validation: 'require-all-validate', + requests: batchRequests.map( ( request ) => ( { + path: request.path, + body: request.data, // Rename 'data' to 'body'. + method: request.method, + headers: request.headers, + } ) ), + }, + } ); + + let batchResults; + + if ( batchResponse.failed ) { + batchResults = batchResponse.responses.map( ( response ) => ( { + error: response?.body, + } ) ); } else { - result.error = response.body; + batchResults = batchResponse.responses.map( ( response ) => { + const result = {}; + if ( response.status >= 200 && response.status < 300 ) { + result.output = response.body; + } else { + result.error = response.body; + } + return result; + } ); } - return result; - } ); + + results.push( ...batchResults ); + } + + return results; } diff --git a/packages/core-data/src/batch/test/default-processor.js b/packages/core-data/src/batch/test/default-processor.js index c6d2515410b82..c712ecdff21aa 100644 --- a/packages/core-data/src/batch/test/default-processor.js +++ b/packages/core-data/src/batch/test/default-processor.js @@ -11,6 +11,18 @@ import defaultProcessor from '../default-processor'; jest.mock( '@wordpress/api-fetch' ); describe( 'defaultProcessor', () => { + const preflightResponse = { + endpoints: [ + { + args: { + requests: { + maxItems: 25, + }, + }, + }, + ], + }; + const requests = [ { path: '/v1/cricketers', @@ -26,7 +38,12 @@ describe( 'defaultProcessor', () => { }, ]; - const expectedFetchOptions = { + const expectedPreflightOptions = { + path: '/batch/v1', + method: 'OPTIONS', + }; + + const expectedBatchOptions = { path: '/batch/v1', method: 'POST', data: { @@ -49,21 +66,26 @@ describe( 'defaultProcessor', () => { }; it( 'handles a successful request', async () => { - apiFetch.mockImplementation( async () => ( { - failed: false, - responses: [ - { - status: 200, - body: 'Lyon', - }, - { - status: 400, - body: 'Error!', - }, - ], - } ) ); + apiFetch.mockImplementation( async ( { method } ) => + method === 'OPTIONS' + ? preflightResponse + : { + failed: false, + responses: [ + { + status: 200, + body: 'Lyon', + }, + { + status: 400, + body: 'Error!', + }, + ], + } + ); const results = await defaultProcessor( requests ); - expect( apiFetch ).toHaveBeenCalledWith( expectedFetchOptions ); + expect( apiFetch ).toHaveBeenCalledWith( expectedPreflightOptions ); + expect( apiFetch ).toHaveBeenCalledWith( expectedBatchOptions ); expect( results ).toEqual( [ { output: 'Lyon' }, { error: 'Error!' }, @@ -71,18 +93,23 @@ describe( 'defaultProcessor', () => { } ); it( 'handles a failed request', async () => { - apiFetch.mockImplementation( async () => ( { - failed: true, - responses: [ - null, - { - status: 400, - body: 'Error!', - }, - ], - } ) ); + apiFetch.mockImplementation( async ( { method } ) => + method === 'OPTIONS' + ? preflightResponse + : { + failed: true, + responses: [ + null, + { + status: 400, + body: 'Error!', + }, + ], + } + ); const results = await defaultProcessor( requests ); - expect( apiFetch ).toHaveBeenCalledWith( expectedFetchOptions ); + expect( apiFetch ).toHaveBeenCalledWith( expectedPreflightOptions ); + expect( apiFetch ).toHaveBeenCalledWith( expectedBatchOptions ); expect( results ).toEqual( [ { error: undefined }, { error: 'Error!' }, diff --git a/packages/customize-widgets/src/components/customize-widgets/index.js b/packages/customize-widgets/src/components/customize-widgets/index.js index 35a91cb89de66..d206108398283 100644 --- a/packages/customize-widgets/src/components/customize-widgets/index.js +++ b/packages/customize-widgets/src/components/customize-widgets/index.js @@ -7,6 +7,7 @@ import { SlotFillProvider, Popover } from '@wordpress/components'; /** * Internal dependencies */ +import ErrorBoundary from '../error-boundary'; import SidebarBlockEditor from '../sidebar-block-editor'; import FocusControl from '../focus-control'; import SidebarControls from '../sidebar-controls'; @@ -42,13 +43,15 @@ export default function CustomizeWidgets( { const activeSidebar = activeSidebarControl && createPortal( - , + + + , activeSidebarControl.container[ 0 ] ); diff --git a/packages/customize-widgets/src/components/error-boundary/index.js b/packages/customize-widgets/src/components/error-boundary/index.js new file mode 100644 index 0000000000000..17047e7f546ea --- /dev/null +++ b/packages/customize-widgets/src/components/error-boundary/index.js @@ -0,0 +1,50 @@ +/** + * WordPress dependencies + */ +import { Component } from '@wordpress/element'; +import { __ } from '@wordpress/i18n'; +import { Button } from '@wordpress/components'; +import { Warning } from '@wordpress/block-editor'; +import { useCopyToClipboard } from '@wordpress/compose'; + +function CopyButton( { text, children } ) { + const ref = useCopyToClipboard( text ); + return ( + + ); +} + +export default class ErrorBoundary extends Component { + constructor() { + super( ...arguments ); + this.state = { + error: null, + }; + } + + componentDidCatch( error ) { + this.setState( { error } ); + } + + render() { + const { error } = this.state; + if ( ! error ) { + return this.props.children; + } + + return ( + + { __( 'Copy Error' ) } + , + ] } + > + { __( 'The editor has encountered an unexpected error.' ) } + + ); + } +} diff --git a/packages/customize-widgets/src/components/inserter/index.js b/packages/customize-widgets/src/components/inserter/index.js index 09ef6bdcb5611..01516947f6dab 100644 --- a/packages/customize-widgets/src/components/inserter/index.js +++ b/packages/customize-widgets/src/components/inserter/index.js @@ -5,13 +5,22 @@ import { __ } from '@wordpress/i18n'; import { __experimentalLibrary as Library } from '@wordpress/block-editor'; import { Button } from '@wordpress/components'; import { useInstanceId } from '@wordpress/compose'; +import { useSelect } from '@wordpress/data'; import { closeSmall } from '@wordpress/icons'; +/** + * Internal dependencies + */ +import { store as customizeWidgetsStore } from '../../store'; + function Inserter( { setIsOpened } ) { const inserterTitleId = useInstanceId( Inserter, 'customize-widget-layout__inserter-panel-title' ); + const insertionPoint = useSelect( ( select ) => + select( customizeWidgetsStore ).__experimentalGetInsertionPoint() + ); return (
setIsOpened( false ) } /> diff --git a/packages/customize-widgets/src/components/inserter/use-inserter.js b/packages/customize-widgets/src/components/inserter/use-inserter.js index e4668dfbd5622..002f76c3b72cc 100644 --- a/packages/customize-widgets/src/components/inserter/use-inserter.js +++ b/packages/customize-widgets/src/components/inserter/use-inserter.js @@ -1,16 +1,27 @@ /** * WordPress dependencies */ -import { useState, useEffect, useCallback } from '@wordpress/element'; +import { useEffect, useCallback } from '@wordpress/element'; +import { useSelect, useDispatch, select as selectStore } from '@wordpress/data'; + +/** + * Internal dependencies + */ +import { store as customizeWidgetsStore } from '../../store'; export default function useInserter( inserter ) { - const [ isInserterOpened, setIsInserterOpened ] = useState( - () => inserter.isOpen + const isInserterOpened = useSelect( ( select ) => + select( customizeWidgetsStore ).isInserterOpened() ); + const { setIsInserterOpened } = useDispatch( customizeWidgetsStore ); useEffect( () => { - return inserter.subscribe( setIsInserterOpened ); - }, [ inserter ] ); + if ( isInserterOpened ) { + inserter.open(); + } else { + inserter.close(); + } + }, [ inserter, isInserterOpened ] ); return [ isInserterOpened, @@ -18,16 +29,14 @@ export default function useInserter( inserter ) { ( updater ) => { let isOpen = updater; if ( typeof updater === 'function' ) { - isOpen = updater( inserter.isOpen ); + isOpen = updater( + selectStore( customizeWidgetsStore ).isInserterOpened() + ); } - if ( isOpen ) { - inserter.open(); - } else { - inserter.close(); - } + setIsInserterOpened( isOpen ); }, - [ inserter ] + [ setIsInserterOpened ] ), ]; } diff --git a/packages/customize-widgets/src/components/more-menu/index.js b/packages/customize-widgets/src/components/more-menu/index.js index ea8a13bdf2047..3ddc71f510156 100644 --- a/packages/customize-widgets/src/components/more-menu/index.js +++ b/packages/customize-widgets/src/components/more-menu/index.js @@ -87,7 +87,7 @@ export default function MoreMenu() { role="menuitem" icon={ external } href={ __( - 'https://wordpress.org/support/article/wordpress-editor/' + 'https://wordpress.org/support/article/block-based-widgets-editor/' ) } target="_blank" rel="noopener noreferrer" diff --git a/packages/customize-widgets/src/components/sidebar-block-editor/index.js b/packages/customize-widgets/src/components/sidebar-block-editor/index.js index 34e38c01e86c4..57f9fffde29fe 100644 --- a/packages/customize-widgets/src/components/sidebar-block-editor/index.js +++ b/packages/customize-widgets/src/components/sidebar-block-editor/index.js @@ -88,6 +88,7 @@ export default function SidebarBlockEditor( { blockEditorSettings, isFixedToolbarActive, keepCaretInsideBlock, + setIsInserterOpened, ] ); if ( isWelcomeGuideActive ) { diff --git a/packages/customize-widgets/src/controls/inserter-outer-section.js b/packages/customize-widgets/src/controls/inserter-outer-section.js index 7091a695578e9..fa0af0971e20c 100644 --- a/packages/customize-widgets/src/controls/inserter-outer-section.js +++ b/packages/customize-widgets/src/controls/inserter-outer-section.js @@ -3,6 +3,12 @@ */ import { ESCAPE } from '@wordpress/keycodes'; import { focus } from '@wordpress/dom'; +import { dispatch } from '@wordpress/data'; + +/** + * Internal dependencies + */ +import { store as customizeWidgetsStore } from '../store'; export default function getInserterOuterSection() { const { @@ -52,12 +58,13 @@ export default function getInserterOuterSection() { 'keydown', ( event ) => { if ( - this.isOpen && + this.expanded() && ( event.keyCode === ESCAPE || event.code === 'Escape' ) ) { event.stopPropagation(); - - this.close(); + dispatch( customizeWidgetsStore ).setIsInserterOpened( + false + ); } }, // Use capture mode to make this run before other event listeners. @@ -65,20 +72,28 @@ export default function getInserterOuterSection() { ); this.contentContainer.addClass( 'widgets-inserter' ); - } - get isOpen() { - return this.expanded(); - } - subscribe( handler ) { - this.expanded.bind( handler ); - return () => this.expanded.unbind( handler ); + + // Set a flag if the state is being changed from open() or close(). + // Don't propagate the event if it's an internal action to prevent infinite loop. + this.isFromInternalAction = false; + this.expanded.bind( () => { + if ( ! this.isFromInternalAction ) { + // Propagate the event to React to sync the state. + dispatch( customizeWidgetsStore ).setIsInserterOpened( + this.expanded() + ); + } + this.isFromInternalAction = false; + } ); } open() { - if ( ! this.isOpen ) { + if ( ! this.expanded() ) { const contentContainer = this.contentContainer[ 0 ]; this.activeElementBeforeExpanded = contentContainer.ownerDocument.activeElement; + this.isFromInternalAction = true; + this.expand( { completeCallback() { // We have to do this in a "completeCallback" or else the elements will not yet be visible/tabbable. @@ -95,11 +110,13 @@ export default function getInserterOuterSection() { } } close() { - if ( this.isOpen ) { + if ( this.expanded() ) { const contentContainer = this.contentContainer[ 0 ]; const activeElement = contentContainer.ownerDocument.activeElement; + this.isFromInternalAction = true; + this.collapse( { completeCallback() { // Return back the focus when closing the inserter. diff --git a/packages/customize-widgets/src/controls/sidebar-control.js b/packages/customize-widgets/src/controls/sidebar-control.js index d980832f44d05..d45a7abd44cd2 100644 --- a/packages/customize-widgets/src/controls/sidebar-control.js +++ b/packages/customize-widgets/src/controls/sidebar-control.js @@ -1,8 +1,14 @@ +/** + * WordPress dependencies + */ +import { dispatch } from '@wordpress/data'; + /** * Internal dependencies */ import SidebarAdapter from '../components/sidebar-block-editor/sidebar-adapter'; import getInserterOuterSection from './inserter-outer-section'; +import { store as customizeWidgetsStore } from '../store'; const getInserterId = ( controlId ) => `widgets-inserter-${ controlId }`; @@ -45,7 +51,9 @@ export default function getSidebarControl() { if ( ! args.unchanged ) { // Close the inserter when the section collapses. if ( ! expanded ) { - this.inserter.close(); + dispatch( customizeWidgetsStore ).setIsInserterOpened( + false + ); } this.subscribers.forEach( ( subscriber ) => diff --git a/packages/customize-widgets/src/controls/sidebar-section.js b/packages/customize-widgets/src/controls/sidebar-section.js index 4d1b00ed716ed..a30f4c242b035 100644 --- a/packages/customize-widgets/src/controls/sidebar-section.js +++ b/packages/customize-widgets/src/controls/sidebar-section.js @@ -45,7 +45,7 @@ export default function getSidebarSection() { ..._args, completeCallback() { controls.forEach( ( control ) => { - control.onChangeSectionExpanded( expanded, args ); + control.onChangeSectionExpanded?.( expanded, args ); } ); _args.completeCallback?.(); }, diff --git a/packages/customize-widgets/src/store/actions.js b/packages/customize-widgets/src/store/actions.js index b156e1e3bbead..e1ee14b4682d7 100644 --- a/packages/customize-widgets/src/store/actions.js +++ b/packages/customize-widgets/src/store/actions.js @@ -15,3 +15,22 @@ export function __unstableToggleFeature( feature ) { feature, }; } + +/** + * Returns an action object used to open/close the inserter. + * + * @param {boolean|Object} value Whether the inserter should be + * opened (true) or closed (false). + * To specify an insertion point, + * use an object. + * @param {string} value.rootClientId The root client ID to insert at. + * @param {number} value.insertionIndex The index to insert at. + * + * @return {Object} Action object. + */ +export function setIsInserterOpened( value ) { + return { + type: 'SET_IS_INSERTER_OPENED', + value, + }; +} diff --git a/packages/customize-widgets/src/store/reducer.js b/packages/customize-widgets/src/store/reducer.js index b3087affe1154..28bfe6fa8cf25 100644 --- a/packages/customize-widgets/src/store/reducer.js +++ b/packages/customize-widgets/src/store/reducer.js @@ -25,6 +25,20 @@ const createWithInitialState = ( initialState ) => ( reducer ) => { return ( state = initialState, action ) => reducer( state, action ); }; +/** + * Reducer tracking whether the inserter is open. + * + * @param {boolean|Object} state + * @param {Object} action + */ +function blockInserterPanel( state = false, action ) { + switch ( action.type ) { + case 'SET_IS_INSERTER_OPENED': + return action.value; + } + return state; +} + /** * Reducer returning the user preferences. * @@ -50,5 +64,6 @@ export const preferences = flow( [ } ); export default combineReducers( { + blockInserterPanel, preferences, } ); diff --git a/packages/customize-widgets/src/store/selectors.js b/packages/customize-widgets/src/store/selectors.js index cc546ec6e5a7e..855bb17780b62 100644 --- a/packages/customize-widgets/src/store/selectors.js +++ b/packages/customize-widgets/src/store/selectors.js @@ -18,3 +18,26 @@ import { get } from 'lodash'; export function __unstableIsFeatureActive( state, feature ) { return get( state.preferences.features, [ feature ], false ); } + +/** + * Returns true if the inserter is opened. + * + * @param {Object} state Global application state. + * + * @return {boolean} Whether the inserter is opened. + */ +export function isInserterOpened( state ) { + return !! state.blockInserterPanel; +} + +/** + * Get the insertion point for the inserter. + * + * @param {Object} state Global application state. + * + * @return {Object} The root client ID and index to insert at. + */ +export function __experimentalGetInsertionPoint( state ) { + const { rootClientId, insertionIndex } = state.blockInserterPanel; + return { rootClientId, insertionIndex }; +} diff --git a/packages/data-controls/README.md b/packages/data-controls/README.md index 561a621d75597..3089cf5c2a4c3 100644 --- a/packages/data-controls/README.md +++ b/packages/data-controls/README.md @@ -20,7 +20,7 @@ The following controls are available on the object returned by the module: -# **apiFetch** +### apiFetch Dispatches a control action for triggering an api fetch call. @@ -45,7 +45,7 @@ _Returns_ - `Object`: The control descriptor. -# **controls** +### controls The default export is what you use to register the controls with your custom store. @@ -64,11 +64,11 @@ import * as actions from './actions'; import * as resolvers from './resolvers'; registerStore( 'my-custom-store', { -reducer, -controls, -actions, -selectors, -resolvers, + reducer, + controls, + actions, + selectors, + resolvers, } ); ``` @@ -76,7 +76,7 @@ _Returns_ - `Object`: An object for registering the default controls with the store. -# **dispatch** +### dispatch Control for dispatching an action in a registered data store. Alias for the `dispatch` control in the `@wordpress/data` package. @@ -85,7 +85,7 @@ _Parameters_ - _args_ `Array`: Arguments passed without change to the `@wordpress/data` control. -# **select** +### select Control for resolving a selector in a registered data store. Alias for the `resolveSelect` built-in control in the `@wordpress/data` package. @@ -94,7 +94,7 @@ _Parameters_ - _args_ `Array`: Arguments passed without change to the `@wordpress/data` control. -# **syncSelect** +### syncSelect Control for calling a selector in a registered data store. Alias for the `select` built-in control in the `@wordpress/data` package. @@ -103,5 +103,4 @@ _Parameters_ - _args_ `Array`: Arguments passed without change to the `@wordpress/data` control. - diff --git a/packages/data/README.md b/packages/data/README.md index 7e2584639cf8d..bd6a5ce50cffc 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -264,7 +264,7 @@ Specific implementation differences from Redux and React Redux: -# **AsyncModeProvider** +### AsyncModeProvider Context Provider Component used to switch the data module component rerendering between Sync and Async modes. @@ -275,19 +275,19 @@ _Usage_ import { useSelect, AsyncModeProvider } from '@wordpress/data'; function BlockCount() { - const count = useSelect( ( select ) => { - return select( 'core/block-editor' ).getBlockCount() - }, [] ); + const count = useSelect( ( select ) => { + return select( 'core/block-editor' ).getBlockCount(); + }, [] ); - return count; + return count; } function App() { - return ( - - - - ); + return ( + + + + ); } ``` @@ -304,7 +304,7 @@ _Returns_ - `WPComponent`: The component to be rendered. -# **combineReducers** +### combineReducers The combineReducers helper function turns an object whose values are different reducing functions into a single reducing function you can pass to registerReducer. @@ -315,18 +315,16 @@ _Usage_ import { combineReducers, createReduxStore, register } from '@wordpress/data'; const prices = ( state = {}, action ) => { - return action.type === 'SET_PRICE' ? - { - ...state, - [ action.item ]: action.price, - } : - state; + return action.type === 'SET_PRICE' + ? { + ...state, + [ action.item ]: action.price, + } + : state; }; const discountPercent = ( state = 0, action ) => { - return action.type === 'START_SALE' ? - action.discountPercent : - state; + return action.type === 'START_SALE' ? action.discountPercent : state; }; const store = createReduxStore( 'my-shop', { @@ -346,11 +344,11 @@ _Returns_ - `Function`: A reducer that invokes every reducer inside the reducers object, and constructs a state object with the same shape. -# **controls** +### controls Undocumented declaration. -# **createReduxStore** +### createReduxStore Creates a data store definition for the provided Redux store options containing properties describing reducer, actions, selectors, controls and resolvers. @@ -361,10 +359,10 @@ _Usage_ import { createReduxStore } from '@wordpress/data'; const store = createReduxStore( 'demo', { - reducer: ( state = 'OK' ) => state, - selectors: { - getValue: ( state ) => state, - }, + reducer: ( state = 'OK' ) => state, + selectors: { + getValue: ( state ) => state, + }, } ); ``` @@ -377,7 +375,7 @@ _Returns_ - `WPDataStore`: Store Object. -# **createRegistry** +### createRegistry Creates a new store registry, given an optional object of initial store configurations. @@ -391,19 +389,19 @@ _Returns_ - `WPDataRegistry`: Data registry. -# **createRegistryControl** +### createRegistryControl Creates a control function that takes additional curried argument with the `registry` object. While a regular control has signature ```js -( action ) => ( iteratorOrPromise ) +( action ) => iteratorOrPromise; ``` where the control works with the `action` that it's bound to, a registry control has signature: ```js -( registry ) => ( action ) => ( iteratorOrPromise ) +( registry ) => ( action ) => iteratorOrPromise; ``` A registry control is typically used to select data or dispatch an action to a registered @@ -420,20 +418,20 @@ _Returns_ - `Function`: Registry control that can be registered with a store. -# **createRegistrySelector** +### createRegistrySelector Creates a selector function that takes additional curried argument with the registry `select` function. While a regular selector has signature ```js -( state, ...selectorArgs ) => ( result ) +( state, ...selectorArgs ) => result; ``` that allows to select data from the store's `state`, a registry selector has signature: ```js -( select ) => ( state, ...selectorArgs ) => ( result ) +( select ) => ( state, ...selectorArgs ) => result; ``` that supports also selecting from other registered stores. @@ -442,14 +440,18 @@ _Usage_ ```js const getCurrentPostId = createRegistrySelector( ( select ) => ( state ) => { - return select( 'core/editor' ).getCurrentPostId(); + return select( 'core/editor' ).getCurrentPostId(); } ); const getPostEdits = createRegistrySelector( ( select ) => ( state ) => { - // calling another registry selector just like any other function - const postType = getCurrentPostType( state ); - const postId = getCurrentPostId( state ); - return select( 'core' ).getEntityRecordEdits( 'postType', postType, postId ); + // calling another registry selector just like any other function + const postType = getCurrentPostType( state ); + const postId = getCurrentPostId( state ); + return select( 'core' ).getEntityRecordEdits( + 'postType', + postType, + postId + ); } ); ``` @@ -466,7 +468,7 @@ _Returns_ - `Function`: Registry selector that can be registered with a store. -# **dispatch** +### dispatch Given the name of a registered store, returns an object of the store's action creators. Calling an action creator will cause it to be dispatched, updating the state value accordingly. @@ -490,7 +492,7 @@ _Returns_ - `Object`: Object containing the action creators. -# **plugins** +### plugins Object of available plugins to use with a registry. @@ -502,7 +504,7 @@ _Type_ - `Object` -# **register** +### register Registers a standard `@wordpress/data` store definition. @@ -512,10 +514,10 @@ _Usage_ import { createReduxStore, register } from '@wordpress/data'; const store = createReduxStore( 'demo', { - reducer: ( state = 'OK' ) => state, - selectors: { - getValue: ( state ) => state, - }, + reducer: ( state = 'OK' ) => state, + selectors: { + getValue: ( state ) => state, + }, } ); register( store ); ``` @@ -524,7 +526,7 @@ _Parameters_ - _store_ `WPDataStore`: Store definition. -# **registerGenericStore** +### registerGenericStore > **Deprecated** Use `register` instead. @@ -535,7 +537,7 @@ _Parameters_ - _key_ `string`: Store registry key. - _config_ `Object`: Configuration (getSelectors, getActions, subscribe). -# **registerStore** +### registerStore > **Deprecated** Use `register` instead. @@ -550,7 +552,7 @@ _Returns_ - `Object`: Registered store object. -# **RegistryConsumer** +### RegistryConsumer A custom react Context consumer exposing the provided `registry` to children components. Used along with the RegistryProvider. @@ -583,7 +585,7 @@ const App = ( { props } ) => { } ``` -# **RegistryProvider** +### RegistryProvider A custom Context provider for exposing the provided `registry` to children components via a consumer. @@ -591,7 +593,7 @@ components via a consumer. See RegistryConsumer documentation for example. -# **resolveSelect** +### resolveSelect Given the name of a registered store, returns an object containing the store's selectors pre-bound to state so that you only need to supply additional arguments, @@ -603,7 +605,7 @@ _Usage_ ```js import { resolveSelect } from '@wordpress/data'; -resolveSelect( 'my-shop' ).getPrice( 'hammer' ).then(console.log) +resolveSelect( 'my-shop' ).getPrice( 'hammer' ).then( console.log ); ``` _Parameters_ @@ -614,7 +616,7 @@ _Returns_ - `Object`: Object containing the store's promise-wrapped selectors. -# **select** +### select Given the name or definition of a registered store, returns an object of the store's selectors. The selector functions are been pre-bound to pass the current state automatically. @@ -636,7 +638,7 @@ _Returns_ - `Object`: Object containing the store's selectors. -# **subscribe** +### subscribe Given a listener function, the function will be called any time the state value of one of the registered stores has changed. This function returns a `unsubscribe` @@ -660,7 +662,7 @@ _Parameters_ - _listener_ `Function`: Callback function. -# **use** +### use Extends a registry to inherit functionality provided by a given plugin. A plugin is an object with properties aligning to that of a registry, merged @@ -670,7 +672,7 @@ _Parameters_ - _plugin_ `Object`: Plugin object. -# **useDispatch** +### useDispatch A custom react hook returning the current registry dispatch actions creators. @@ -688,21 +690,25 @@ import { useDispatch, useSelect } from '@wordpress/data'; import { useCallback } from '@wordpress/element'; function Button( { onClick, children } ) { - return + return ( + + ); } const SaleButton = ( { children } ) => { - const { stockNumber } = useSelect( - ( select ) => select( 'my-shop' ).getStockNumber(), - [] - ); - const { startSale } = useDispatch( 'my-shop' ); - const onClick = useCallback( () => { - const discountPercent = stockNumber > 50 ? 10: 20; - startSale( discountPercent ); - }, [ stockNumber ] ); - return -} + const { stockNumber } = useSelect( + ( select ) => select( 'my-shop' ).getStockNumber(), + [] + ); + const { startSale } = useDispatch( 'my-shop' ); + const onClick = useCallback( () => { + const discountPercent = stockNumber > 50 ? 10 : 20; + startSale( discountPercent ); + }, [ stockNumber ] ); + return ; +}; // Rendered somewhere in the application: // @@ -717,7 +723,7 @@ _Returns_ - `Function`: A custom react hook. -# **useRegistry** +### useRegistry A custom react hook exposing the registry context for use. @@ -729,30 +735,27 @@ It acts similarly to the `useContext` react hook. Note: Generally speaking, `useRegistry` is a low level hook that in most cases won't be needed for implementation. Most interactions with the `@wordpress/data` -API can be performed via the `useSelect` hook, or the `withSelect` and +API can be performed via the `useSelect` hook, or the `withSelect` and `withDispatch` higher order components. _Usage_ ```js -import { - RegistryProvider, - createRegistry, - useRegistry, -} from '@wordpress/data'; +import { RegistryProvider, createRegistry, useRegistry } from '@wordpress/data'; const registry = createRegistry( {} ); const SomeChildUsingRegistry = ( props ) => { - const registry = useRegistry( registry ); - // ...logic implementing the registry in other react hooks. + const registry = useRegistry( registry ); + // ...logic implementing the registry in other react hooks. }; - const ParentProvidingRegistry = ( props ) => { - return - - + return ( + + + + ); }; ``` @@ -760,7 +763,7 @@ _Returns_ - `Function`: A custom react hook exposing the registry context value. -# **useSelect** +### useSelect Custom react hook for retrieving props from registered selectors. @@ -773,13 +776,16 @@ _Usage_ import { useSelect } from '@wordpress/data'; function HammerPriceDisplay( { currency } ) { - const price = useSelect( ( select ) => { - return select( 'my-shop' ).getPrice( 'hammer', currency ) - }, [ currency ] ); - return new Intl.NumberFormat( 'en-US', { - style: 'currency', - currency, - } ).format( price ); + const price = useSelect( + ( select ) => { + return select( 'my-shop' ).getPrice( 'hammer', currency ); + }, + [ currency ] + ); + return new Intl.NumberFormat( 'en-US', { + style: 'currency', + currency, + } ).format( price ); } // Rendered in the application: @@ -803,12 +809,12 @@ function because your component won't re-render on a data change.** import { useSelect } from '@wordpress/data'; function Paste( { children } ) { - const { getSettings } = useSelect( 'my-shop' ); - function onPaste() { - // Do something with the settings. - const settings = getSettings(); - } - return
{ children }
; + const { getSettings } = useSelect( 'my-shop' ); + function onPaste() { + // Do something with the settings. + const settings = getSettings(); + } + return
{ children }
; } ``` @@ -821,7 +827,7 @@ _Returns_ - `Function`: A custom react hook. -# **withDispatch** +### withDispatch Higher-order component used to add dispatch props using registered action creators. @@ -830,20 +836,24 @@ _Usage_ ```jsx function Button( { onClick, children } ) { - return ; + return ( + + ); } import { withDispatch } from '@wordpress/data'; const SaleButton = withDispatch( ( dispatch, ownProps ) => { - const { startSale } = dispatch( 'my-shop' ); - const { discountPercent } = ownProps; - - return { - onClick() { - startSale( discountPercent ); - }, - }; + const { startSale } = dispatch( 'my-shop' ); + const { discountPercent } = ownProps; + + return { + onClick() { + startSale( discountPercent ); + }, + }; } )( Button ); // Rendered in the application: @@ -866,21 +876,25 @@ only. ```jsx function Button( { onClick, children } ) { - return ; + return ( + + ); } import { withDispatch } from '@wordpress/data'; const SaleButton = withDispatch( ( dispatch, ownProps, { select } ) => { - // Stock number changes frequently. - const { getStockNumber } = select( 'my-shop' ); - const { startSale } = dispatch( 'my-shop' ); - return { - onClick() { - const discountPercent = getStockNumber() > 50 ? 10 : 20; - startSale( discountPercent ); - }, - }; + // Stock number changes frequently. + const { getStockNumber } = select( 'my-shop' ); + const { startSale } = dispatch( 'my-shop' ); + return { + onClick() { + const discountPercent = getStockNumber() > 50 ? 10 : 20; + startSale( discountPercent ); + }, + }; } )( Button ); // Rendered in the application: @@ -900,7 +914,7 @@ _Returns_ - `WPComponent`: Enhanced component with merged dispatcher props. -# **withRegistry** +### withRegistry Higher-order component which renders the original component with the current registry context passed as its `registry` prop. @@ -913,7 +927,7 @@ _Returns_ - `WPComponent`: Enhanced component. -# **withSelect** +### withSelect Higher-order component used to inject state-derived props using registered selectors. @@ -957,7 +971,6 @@ _Returns_ - `WPComponent`: Enhanced component with merged state data props. - ## Going further diff --git a/packages/date/README.md b/packages/date/README.md index 7e1488f8c18b3..3f6c266aa5b59 100644 --- a/packages/date/README.md +++ b/packages/date/README.md @@ -16,7 +16,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If -# **date** +### date Formats a date (like `date()` in PHP). @@ -35,7 +35,7 @@ _Returns_ - `string`: Formatted date in English. -# **dateI18n** +### dateI18n Formats a date (like `wp_date()` in PHP), translating it into site's locale. @@ -57,7 +57,7 @@ _Returns_ - `string`: Formatted date. -# **format** +### format Formats a date. Does not alter the date's timezone. @@ -70,7 +70,7 @@ _Returns_ - `string`: Formatted date. -# **getDate** +### getDate Create and return a JavaScript Date Object from a date string in the WP timezone. @@ -82,7 +82,7 @@ _Returns_ - `Date`: Date -# **gmdate** +### gmdate Formats a date (like `date()` in PHP), in the UTC timezone. @@ -95,7 +95,7 @@ _Returns_ - `string`: Formatted date in English. -# **gmdateI18n** +### gmdateI18n Formats a date (like `wp_date()` in PHP), translating it into site's locale and using the UTC timezone. @@ -109,7 +109,7 @@ _Returns_ - `string`: Formatted date. -# **isInTheFuture** +### isInTheFuture Check whether a date is considered in the future according to the WordPress settings. @@ -121,7 +121,7 @@ _Returns_ - `boolean`: Is in the future. -# **setSettings** +### setSettings Adds a locale to moment, using the format supplied by `wp_localize_script()`. @@ -129,7 +129,6 @@ _Parameters_ - _dateSettings_ `DateSettings`: Settings, including locale data. -

Code is Poetry.

diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md index 2578199dded9d..22fa761c8b942 100644 --- a/packages/deprecated/README.md +++ b/packages/deprecated/README.md @@ -36,7 +36,7 @@ addAction( -# **default** +### default Logs a message to notify developers about a deprecated feature. @@ -67,7 +67,7 @@ _Parameters_ - _options.link_ `[string]`: Link to documentation - _options.hint_ `[string]`: Additional message to help transition away from the deprecated feature. -# **logged** +### logged Object map tracking messages which have been logged, for use in ensuring a message is only logged once. @@ -76,7 +76,6 @@ _Type_ - `Record` -

Code is Poetry.

diff --git a/packages/docgen/lib/markdown/formatter.js b/packages/docgen/lib/markdown/formatter.js index 1a3a7894d56f2..a2fcbd081c20a 100644 --- a/packages/docgen/lib/markdown/formatter.js +++ b/packages/docgen/lib/markdown/formatter.js @@ -59,10 +59,6 @@ const getHeading = ( index, text ) => { return '#'.repeat( index ) + ' ' + text; }; -const getSymbolHeading = ( text ) => { - return `# **${ text }**`; -}; - const getTypeOutput = ( tag ) => { if ( tag.optional ) { return `\`[${ tag.type }]\``; @@ -98,7 +94,7 @@ module.exports = ( } ); if ( symbols && symbols.length > 0 ) { symbols.forEach( ( symbol ) => { - docs.push( getSymbolHeading( symbol.name ) ); + docs.push( getHeading( headingIndex, symbol.name ) ); formatDeprecated( getSymbolTagsByName( symbol, 'deprecated' ), docs diff --git a/packages/docgen/test/formatter-markdown.js b/packages/docgen/test/formatter-markdown.js index eedad6bf018cf..b2904d4247e82 100644 --- a/packages/docgen/test/formatter-markdown.js +++ b/packages/docgen/test/formatter-markdown.js @@ -36,7 +36,7 @@ describe( 'Formatter', () => { 'API docs' ); expect( docs ).toBe( - '# API docs\n\n# **myDeclaration**\n\nMy declaration example.\n\n*Parameters*\n\n- *firstParam* `number`: First declaration parameter.\n\n*Returns*\n\n- `number`: The result of the declaration.\n' + '# API docs\n\n## myDeclaration\n\nMy declaration example.\n\n*Parameters*\n\n- *firstParam* `number`: First declaration parameter.\n\n*Returns*\n\n- `number`: The result of the declaration.\n' ); } ); } ); diff --git a/packages/dom-ready/README.md b/packages/dom-ready/README.md index 92c09bc33bbd0..08ca78f382c75 100644 --- a/packages/dom-ready/README.md +++ b/packages/dom-ready/README.md @@ -16,7 +16,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If -# **default** +### default Specify a function to execute when the DOM is fully loaded. @@ -25,7 +25,7 @@ _Usage_ ```js import domReady from '@wordpress/dom-ready'; -domReady( function() { +domReady( function () { //do something after DOM loads. } ); ``` @@ -36,8 +36,7 @@ _Parameters_ _Returns_ -- `void`: - +- `void`: diff --git a/packages/dom/README.md b/packages/dom/README.md index 3279aaed867e2..e6378ae8c98d7 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -14,7 +14,7 @@ npm install @wordpress/dom --save -# **computeCaretRect** +### computeCaretRect Get the rectangle for the selection in a container. @@ -26,7 +26,7 @@ _Returns_ - `DOMRect | null`: The rectangle. -# **documentHasSelection** +### documentHasSelection Check whether the current document has a selection. This checks for both focus in an input field and general text selection. @@ -39,7 +39,7 @@ _Returns_ - `boolean`: True if there is selection, false if not. -# **documentHasTextSelection** +### documentHasTextSelection Check whether the current document has selected text. This applies to ranges of text in the document, and not selection inside and