Skip to content

Commit

Permalink
Blocks: Rename patterns to variations in the Block API
Browse files Browse the repository at this point in the history
  • Loading branch information
@gziolo
gziolo committed Jan 30, 2020
1 parent d66d53b commit 983aacf
Show file tree
Hide file tree
Showing 8 changed files with 185 additions and 185 deletions.
98 changes: 49 additions & 49 deletions packages/blocks/src/api/registration.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,58 +65,58 @@ import { DEPRECATED_ENTRY_KEYS } from './constants';
*/

/**
* Named block pattern scopes.
* Named block variation scopes.
*
* @typedef {'block'|'inserter'} WPBlockPatternScope
* @typedef {'block'|'inserter'} WPBlockVariationScope
*/

/**
* An object describing a pattern defined for the block type.
* An object describing a variation defined for the block type.
*
* @typedef {Object} WPBlockPattern
* @typedef {Object} WPBlockVariation
*
* @property {string} name The unique and machine-readable name.
* @property {string} title A human-readable pattern title.
* @property {string} description A detailed pattern description.
* @property {WPIcon} [icon] An icon helping to visualize the pattern.
* @property {boolean} [isDefault] Indicates whether the current pattern is
* the default one. Defaults to `false`.
* @property {Object} [attributes] Values which override block attributes.
* @property {Array[]} [innerBlocks] Initial configuration of nested blocks.
* @property {Object} [example] Example provides structured data for
* the block preview. You can set to
* `undefined` to disable the preview shown
* for the block type.
* @property {WPBlockPatternScope[]} [scope] The list of scopes where the pattern
* is applicable. When not provided, it
* assumes all available scopes.
* @property {string} name The unique and machine-readable name.
* @property {string} title A human-readable variation title.
* @property {string} description A detailed variation description.
* @property {WPIcon} [icon] An icon helping to visualize the variation.
* @property {boolean} [isDefault] Indicates whether the current variation is
* the default one. Defaults to `false`.
* @property {Object} [attributes] Values which override block attributes.
* @property {Array[]} [innerBlocks] Initial configuration of nested blocks.
* @property {Object} [example] Example provides structured data for
* the block preview. You can set to
* `undefined` to disable the preview shown
* for the block type.
* @property {WPBlockVariationScope[]} [scope] The list of scopes where the variation
* is applicable. When not provided, it
* assumes all available scopes.
*/

/**
* Defined behavior of a block type.
*
* @typedef {Object} WPBlock
*
* @property {string} name Block type's namespaced name.
* @property {string} title Human-readable block type label.
* @property {string} description A detailed block type description.
* @property {string} category Block type category classification,
* used in search interfaces to arrange
* block types by category.
* @property {WPBlockTypeIcon} [icon] Block type icon.
* @property {string[]} [keywords] Additional keywords to produce block
* type as result in search interfaces.
* @property {Object} [attributes] Block type attributes.
* @property {WPComponent} [save] Optional component describing
* serialized markup structure of a
* block type.
* @property {WPComponent} edit Component rendering an element to
* manipulate the attributes of a block
* in the context of an editor.
* @property {WPBlockPattern[]} [patterns] The list of block patterns.
* @property {Object} [example] Example provides structured data for
* the block preview. When not defined
* then no preview is shown.
* @property {string} name Block type's namespaced name.
* @property {string} title Human-readable block type label.
* @property {string} description A detailed block type description.
* @property {string} category Block type category classification,
* used in search interfaces to arrange
* block types by category.
* @property {WPBlockTypeIcon} [icon] Block type icon.
* @property {string[]} [keywords] Additional keywords to produce block
* type as result in search interfaces.
* @property {Object} [attributes] Block type attributes.
* @property {WPComponent} [save] Optional component describing
* serialized markup structure of a
* block type.
* @property {WPComponent} edit Component rendering an element to
* manipulate the attributes of a block
* in the context of an editor.
* @property {WPBlockVariation[]} [variations] The list of block variations.
* @property {Object} [example] Example provides structured data for
* the block preview. When not defined
* then no preview is shown.
*/

/**
Expand Down Expand Up @@ -499,21 +499,21 @@ export const unregisterBlockStyle = ( blockName, styleVariationName ) => {
};

/**
* Registers a new block pattern for the given block.
* Registers a new block variation for the given block.
*
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {WPBlockPattern} pattern Object describing a block pattern.
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {WPBlockVariation} variation Object describing a block variation.
*/
export const __experimentalRegisterBlockPattern = ( blockName, pattern ) => {
dispatch( 'core/blocks' ).__experimentalAddBlockPatterns( blockName, pattern );
export const __experimentalRegisterBlockVariation = ( blockName, variation ) => {
dispatch( 'core/blocks' ).__experimentalAddBlockVariations( blockName, variation );
};

/**
* Unregisters a block pattern defined for the given block.
* Unregisters a block variation defined for the given block.
*
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {string} patternName Name of the pattern defined for the block.
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {string} variationName Name of the variation defined for the block.
*/
export const __experimentalUnregisterBlockPattern = ( blockName, patternName ) => {
dispatch( 'core/blocks' ).__experimentalRemoveBlockPatterns( blockName, patternName );
export const __experimentalUnregisterBlockVariation = ( blockName, variationName ) => {
dispatch( 'core/blocks' ).__experimentalRemoveBlockVariations( blockName, variationName );
};
6 changes: 3 additions & 3 deletions packages/blocks/src/api/test/registration.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,7 @@ describe( 'blocks', () => {
},
attributes: {},
keywords: [],
patterns: [],
variations: [],
},
] );
const oldBlock = unregisterBlockType( 'core/test-block' );
Expand Down Expand Up @@ -607,7 +607,7 @@ describe( 'blocks', () => {
},
attributes: {},
keywords: [],
patterns: [],
variations: [],
},
{
name: 'core/test-block-with-settings',
Expand All @@ -620,7 +620,7 @@ describe( 'blocks', () => {
},
attributes: {},
keywords: [],
patterns: [],
variations: [],
},
] );
} );
Expand Down
20 changes: 10 additions & 10 deletions packages/blocks/src/store/actions.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,33 +64,33 @@ export function removeBlockStyles( blockName, styleNames ) {
}

/**
* Returns an action object used in signalling that new block patterns have been added.
* Returns an action object used in signalling that new block variations have been added.
*
* @param {string} blockName Block name.
* @param {WPBlockPattern|WPBlockPattern[]} patterns Block patterns.
* @param {WPBlockVariation|WPBlockVariation[]} variations Block variations.
*
* @return {Object} Action object.
*/
export function __experimentalAddBlockPatterns( blockName, patterns ) {
export function __experimentalAddBlockVariations( blockName, variations ) {
return {
type: 'ADD_BLOCK_PATTERNS',
patterns: castArray( patterns ),
type: 'ADD_BLOCK_VARIATIONS',
variations: castArray( variations ),
blockName,
};
}

/**
* Returns an action object used in signalling that block patterns have been removed.
* Returns an action object used in signalling that block variations have been removed.
*
* @param {string} blockName Block name.
* @param {string|string[]} patternNames Block pattern names.
* @param {string|string[]} variationNames Block variation names.
*
* @return {Object} Action object.
*/
export function __experimentalRemoveBlockPatterns( blockName, patternNames ) {
export function __experimentalRemoveBlockVariations( blockName, variationNames ) {
return {
type: 'REMOVE_BLOCK_PATTERNS',
patternNames: castArray( patternNames ),
type: 'REMOVE_BLOCK_VARIATIONS',
variationNames: castArray( variationNames ),
blockName,
};
}
Expand Down
20 changes: 10 additions & 10 deletions packages/blocks/src/store/reducer.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,39 +98,39 @@ export function blockStyles( state = {}, action ) {
}

/**
* Reducer managing the block patterns.
* Reducer managing the block variations.
*
* @param {Object} state Current state.
* @param {Object} action Dispatched action.
*
* @return {Object} Updated state.
*/
export function blockPatterns( state = {}, action ) {
export function blockVariations( state = {}, action ) {
switch ( action.type ) {
case 'ADD_BLOCK_TYPES':
return {
...state,
...mapValues( keyBy( action.blockTypes, 'name' ), ( blockType ) => {
return uniqBy( [
...get( blockType, [ 'patterns' ], [] ),
...get( blockType, [ 'variations' ], [] ),
...get( state, [ blockType.name ], [] ),
], ( pattern ) => pattern.name );
], ( variation ) => variation.name );
} ),
};
case 'ADD_BLOCK_PATTERNS':
case 'ADD_BLOCK_VARIATIONS':
return {
...state,
[ action.blockName ]: uniqBy( [
...get( state, [ action.blockName ], [] ),
...( action.patterns ),
], ( pattern ) => pattern.name ),
...( action.variations ),
], ( variation ) => variation.name ),
};
case 'REMOVE_BLOCK_PATTERNS':
case 'REMOVE_BLOCK_VARIATIONS':
return {
...state,
[ action.blockName ]: filter(
get( state, [ action.blockName ], [] ),
( pattern ) => action.patternNames.indexOf( pattern.name ) === -1,
( variation ) => action.variationNames.indexOf( variation.name ) === -1,
),
};
}
Expand Down Expand Up @@ -219,7 +219,7 @@ export function collections( state = {}, action ) {
export default combineReducers( {
blockTypes,
blockStyles,
blockPatterns,
blockVariations,
defaultBlockName,
freeformFallbackBlockName,
unregisteredFallbackBlockName,
Expand Down
48 changes: 24 additions & 24 deletions packages/blocks/src/store/selectors.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import {
some,
} from 'lodash';

/** @typedef {import('../api/registration').WPBlockPatternScope} WPBlockPatternScope */
/** @typedef {import('../api/registration').WPBlockVariationScope} WPBlockVariationScope */

/**
* Given a block name or block type object, returns the corresponding
Expand Down Expand Up @@ -43,13 +43,13 @@ export const getBlockTypes = createSelector(
return Object.values( state.blockTypes ).map( ( blockType ) => {
return {
...blockType,
patterns: __experimentalGetBlockPatterns( state, blockType.name ),
variations: __experimentalGetBlockVariations( state, blockType.name ),
};
} );
},
( state ) => [
state.blockTypes,
state.blockPatterns,
state.blockVariations,
]
);

Expand Down Expand Up @@ -78,40 +78,40 @@ export function getBlockStyles( state, name ) {
}

/**
* Returns block patterns by block name.
* Returns block variations by block name.
*
* @param {Object} state Data state.
* @param {string} blockName Block type name.
* @param {WPBlockPatternScope} [scope] Block pattern scope name.
* @param {Object} state Data state.
* @param {string} blockName Block type name.
* @param {WPBlockVariationScope} [scope] Block variation scope name.
*
* @return {(WPBlockPattern[]|void)} Block patterns.
* @return {(WPBlockPattern[]|void)} Block variations.
*/
export function __experimentalGetBlockPatterns( state, blockName, scope ) {
const patterns = state.blockPatterns[ blockName ];
if ( ! patterns || ! scope ) {
return patterns;
export function __experimentalGetBlockVariations( state, blockName, scope ) {
const variations = state.blockVariations[ blockName ];
if ( ! variations || ! scope ) {
return variations;
}
return patterns.filter( ( pattern ) => {
return ! pattern.scope || pattern.scope.includes( scope );
return variations.filter( ( variation ) => {
return ! variation.scope || variation.scope.includes( scope );
} );
}

/**
* Returns the default block pattern for the given block type.
* When there are multiple patterns annotated as the default one,
* Returns the default block variation for the given block type.
* When there are multiple variations annotated as the default one,
* the last added item is picked. This simplifies registering overrides.
* When there is no default pattern set, it returns the first item.
* When there is no default variation set, it returns the first item.
*
* @param {Object} state Data state.
* @param {string} blockName Block type name.
* @param {WPBlockPatternScope} [scope] Block pattern scope name.
* @param {Object} state Data state.
* @param {string} blockName Block type name.
* @param {WPBlockVariationScope} [scope] Block variation scope name.
*
* @return {?WPBlockPattern} The default block pattern.
* @return {?WPBlockPattern} The default block variation.
*/
export function __experimentalGetDefaultBlockPattern( state, blockName, scope ) {
const patterns = __experimentalGetBlockPatterns( state, blockName, scope );
export function __experimentalGetDefaultBlockVariation( state, blockName, scope ) {
const variations = __experimentalGetBlockVariations( state, blockName, scope );

return findLast( patterns, 'isDefault' ) || first( patterns );
return findLast( variations, 'isDefault' ) || first( variations );
}

/**
Expand Down
Loading

0 comments on commit 983aacf

Please sign in to comment.