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