@wordpress/blocks
Version:
Block API for WordPress.
722 lines (608 loc) • 25.6 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", {
value: true
});
exports.unstable__bootstrapServerSideBlockDefinitions = unstable__bootstrapServerSideBlockDefinitions;
exports.registerBlockType = registerBlockType;
exports.registerBlockTypeFromMetadata = registerBlockTypeFromMetadata;
exports.registerBlockCollection = registerBlockCollection;
exports.unregisterBlockCollection = unregisterBlockCollection;
exports.unregisterBlockType = unregisterBlockType;
exports.setFreeformContentHandlerName = setFreeformContentHandlerName;
exports.getFreeformContentHandlerName = getFreeformContentHandlerName;
exports.getGroupingBlockName = getGroupingBlockName;
exports.setUnregisteredTypeHandlerName = setUnregisteredTypeHandlerName;
exports.getUnregisteredTypeHandlerName = getUnregisteredTypeHandlerName;
exports.setDefaultBlockName = setDefaultBlockName;
exports.setGroupingBlockName = setGroupingBlockName;
exports.getDefaultBlockName = getDefaultBlockName;
exports.getBlockType = getBlockType;
exports.getBlockTypes = getBlockTypes;
exports.getBlockSupport = getBlockSupport;
exports.hasBlockSupport = hasBlockSupport;
exports.isReusableBlock = isReusableBlock;
exports.isTemplatePart = isTemplatePart;
exports.unregisterBlockVariation = exports.registerBlockVariation = exports.getBlockVariations = exports.unregisterBlockStyle = exports.registerBlockStyle = exports.hasChildBlocksWithInserterSupport = exports.hasChildBlocks = exports.getChildBlockNames = exports.serverSideBlockDefinitions = void 0;
var _lodash = require("lodash");
var _hooks = require("@wordpress/hooks");
var _data = require("@wordpress/data");
var _i18n = require("@wordpress/i18n");
var _icons = require("@wordpress/icons");
var _utils = require("./utils");
var _constants = require("./constants");
var _store = require("../store");
/* eslint no-console: [ 'error', { allow: [ 'error', 'warn' ] } ] */
/**
* External dependencies
*/
/**
* WordPress dependencies
*/
/**
* Internal dependencies
*/
const i18nBlockSchema = {
title: "block title",
description: "block description",
keywords: ["block keyword"],
styles: [{
label: "block style label"
}],
variations: [{
title: "block variation title",
description: "block variation description",
keywords: ["block variation keyword"]
}]
};
/**
* An icon type definition. One of a Dashicon slug, an element,
* or a component.
*
* @typedef {(string|WPElement|WPComponent)} WPIcon
*
* @see https://developer.wordpress.org/resource/dashicons/
*/
/**
* Render behavior of a block type icon; one of a Dashicon slug, an element,
* or a component.
*
* @typedef {WPIcon} WPBlockTypeIconRender
*/
/**
* An object describing a normalized block type icon.
*
* @typedef {Object} WPBlockTypeIconDescriptor
*
* @property {WPBlockTypeIconRender} src Render behavior of the icon,
* one of a Dashicon slug, an
* element, or a component.
* @property {string} background Optimal background hex string
* color when displaying icon.
* @property {string} foreground Optimal foreground hex string
* color when displaying icon.
* @property {string} shadowColor Optimal shadow hex string
* color when displaying icon.
*/
/**
* Value to use to render the icon for a block type in an editor interface,
* either a Dashicon slug, an element, a component, or an object describing
* the icon.
*
* @typedef {(WPBlockTypeIconDescriptor|WPBlockTypeIconRender)} WPBlockTypeIcon
*/
/**
* Named block variation scopes.
*
* @typedef {'block'|'inserter'|'transform'} WPBlockVariationScope
*/
/**
* An object describing a variation defined for the block type.
*
* @typedef {Object} WPBlockVariation
*
* @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 {string} [category] Block type category classification,
* used in search interfaces to arrange
* block types by category.
* @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.
* @property {string[]} [keywords] An array of terms (which can be translated)
* that help users discover the variation
* while searching.
* @property {Function|string[]} [isActive] This can be a function or an array of block attributes.
* Function that accepts a block's attributes and the
* variation's attributes and determines if a variation is active.
* This function doesn't try to find a match dynamically based
* on all block's attributes, as in many cases some attributes are irrelevant.
* An example would be for `embed` block where we only care
* about `providerNameSlug` attribute's value.
* We can also use a `string[]` to tell which attributes
* should be compared as a shorthand. Each attributes will
* be matched and the variation will be active if all of them are matching.
*/
/**
* 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 {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.
*/
/**
* Mapping of legacy category slugs to their latest normal values, used to
* accommodate updates of the default set of block categories.
*
* @type {Record<string,string>}
*/
const LEGACY_CATEGORY_MAPPING = {
common: 'text',
formatting: 'text',
layout: 'design'
};
const serverSideBlockDefinitions = {};
/**
* Sets the server side block definition of blocks.
*
* @param {Object} definitions Server-side block definitions
*/
// eslint-disable-next-line camelcase
exports.serverSideBlockDefinitions = serverSideBlockDefinitions;
function unstable__bootstrapServerSideBlockDefinitions(definitions) {
for (const blockName of Object.keys(definitions)) {
// Don't overwrite if already set. It covers the case when metadata
// was initialized from the server.
if (serverSideBlockDefinitions[blockName]) {
// We still need to polyfill `apiVersion` for WordPress version
// lower than 5.7. If it isn't present in the definition shared
// from the server, we try to fallback to the definition passed.
// @see https://github.com/WordPress/gutenberg/pull/29279
if (serverSideBlockDefinitions[blockName].apiVersion === undefined && definitions[blockName].apiVersion) {
serverSideBlockDefinitions[blockName].apiVersion = definitions[blockName].apiVersion;
}
continue;
}
serverSideBlockDefinitions[blockName] = (0, _lodash.mapKeys)((0, _lodash.pickBy)(definitions[blockName], value => !(0, _lodash.isNil)(value)), (value, key) => (0, _lodash.camelCase)(key));
}
}
/**
* Registers a new block provided a unique name and an object defining its
* behavior. Once registered, the block is made available as an option to any
* editor interface where blocks are implemented.
*
* @param {string} name Block name.
* @param {Object} settings Block settings.
*
* @return {?WPBlock} The block, if it has been successfully registered;
* otherwise `undefined`.
*/
function registerBlockType(name, settings) {
settings = {
name,
icon: _icons.blockDefault,
keywords: [],
attributes: {},
providesContext: {},
usesContext: [],
supports: {},
styles: [],
save: () => null,
...(serverSideBlockDefinitions === null || serverSideBlockDefinitions === void 0 ? void 0 : serverSideBlockDefinitions[name]),
...settings
};
if (typeof name !== 'string') {
console.error('Block names must be strings.');
return;
}
if (!/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test(name)) {
console.error('Block names must contain a namespace prefix, include only lowercase alphanumeric characters or dashes, and start with a letter. Example: my-plugin/my-custom-block');
return;
}
if ((0, _data.select)(_store.store).getBlockType(name)) {
console.error('Block "' + name + '" is already registered.');
return;
}
const preFilterSettings = { ...settings
};
settings = (0, _hooks.applyFilters)('blocks.registerBlockType', settings, name);
if (settings.deprecated) {
settings.deprecated = settings.deprecated.map(deprecation => (0, _lodash.pick)( // Only keep valid deprecation keys.
(0, _hooks.applyFilters)('blocks.registerBlockType', // Merge deprecation keys with pre-filter settings
// so that filters that depend on specific keys being
// present don't fail.
{ // Omit deprecation keys here so that deprecations
// can opt out of specific keys like "supports".
...(0, _lodash.omit)(preFilterSettings, _constants.DEPRECATED_ENTRY_KEYS),
...deprecation
}, name), _constants.DEPRECATED_ENTRY_KEYS));
}
if (!(0, _lodash.isPlainObject)(settings)) {
console.error('Block settings must be a valid object.');
return;
}
if (!(0, _lodash.isFunction)(settings.save)) {
console.error('The "save" property must be a valid function.');
return;
}
if ('edit' in settings && !(0, _lodash.isFunction)(settings.edit)) {
console.error('The "edit" property must be a valid function.');
return;
} // Canonicalize legacy categories to equivalent fallback.
if (LEGACY_CATEGORY_MAPPING.hasOwnProperty(settings.category)) {
settings.category = LEGACY_CATEGORY_MAPPING[settings.category];
}
if ('category' in settings && !(0, _lodash.some)((0, _data.select)(_store.store).getCategories(), {
slug: settings.category
})) {
console.warn('The block "' + name + '" is registered with an invalid category "' + settings.category + '".');
delete settings.category;
}
if (!('title' in settings) || settings.title === '') {
console.error('The block "' + name + '" must have a title.');
return;
}
if (typeof settings.title !== 'string') {
console.error('Block titles must be strings.');
return;
}
settings.icon = (0, _utils.normalizeIconObject)(settings.icon);
if (!(0, _utils.isValidIcon)(settings.icon.src)) {
console.error('The icon passed is invalid. ' + 'The icon should be a string, an element, a function, or an object following the specifications documented in https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#icon-optional');
return;
}
(0, _data.dispatch)(_store.store).addBlockTypes(settings);
return settings;
}
/**
* Translates block settings provided with metadata using the i18n schema.
*
* @param {string|string[]|Object[]} i18nSchema I18n schema for the block setting.
* @param {string|string[]|Object[]} settingValue Value for the block setting.
* @param {string} textdomain Textdomain to use with translations.
*
* @return {string|string[]|Object[]} Translated setting.
*/
function translateBlockSettingUsingI18nSchema(i18nSchema, settingValue, textdomain) {
if ((0, _lodash.isString)(i18nSchema) && (0, _lodash.isString)(settingValue)) {
// eslint-disable-next-line @wordpress/i18n-no-variables, @wordpress/i18n-text-domain
return (0, _i18n._x)(settingValue, i18nSchema, textdomain);
}
if ((0, _lodash.isArray)(i18nSchema) && !(0, _lodash.isEmpty)(i18nSchema) && (0, _lodash.isArray)(settingValue)) {
return settingValue.map(value => translateBlockSettingUsingI18nSchema(i18nSchema[0], value, textdomain));
}
if ((0, _lodash.isObject)(i18nSchema) && !(0, _lodash.isEmpty)(i18nSchema) && (0, _lodash.isObject)(settingValue)) {
return Object.keys(settingValue).reduce((accumulator, key) => {
if (!i18nSchema[key]) {
accumulator[key] = settingValue[key];
return accumulator;
}
accumulator[key] = translateBlockSettingUsingI18nSchema(i18nSchema[key], settingValue[key], textdomain);
return accumulator;
}, {});
}
return settingValue;
}
/**
* Registers a new block provided from metadata stored in `block.json` file.
* It uses `registerBlockType` internally.
*
* @see registerBlockType
*
* @param {Object} metadata Block metadata loaded from `block.json`.
* @param {string} metadata.name Block name.
* @param {string} metadata.textdomain Textdomain to use with translations.
* @param {Object} additionalSettings Additional block settings.
*
* @return {?WPBlock} The block, if it has been successfully registered;
* otherwise `undefined`.
*/
function registerBlockTypeFromMetadata({
name,
textdomain,
...metadata
}, additionalSettings) {
const allowedFields = ['apiVersion', 'title', 'category', 'parent', 'icon', 'description', 'keywords', 'attributes', 'providesContext', 'usesContext', 'supports', 'styles', 'example', 'variations'];
const settings = (0, _lodash.pick)(metadata, allowedFields);
if (textdomain) {
Object.keys(i18nBlockSchema).forEach(key => {
if (!settings[key]) {
return;
}
settings[key] = translateBlockSettingUsingI18nSchema(i18nBlockSchema[key], settings[key], textdomain);
});
}
unstable__bootstrapServerSideBlockDefinitions({
[name]: settings
});
return registerBlockType(name, additionalSettings);
}
/**
* Registers a new block collection to group blocks in the same namespace in the inserter.
*
* @param {string} namespace The namespace to group blocks by in the inserter; corresponds to the block namespace.
* @param {Object} settings The block collection settings.
* @param {string} settings.title The title to display in the block inserter.
* @param {Object} [settings.icon] The icon to display in the block inserter.
*/
function registerBlockCollection(namespace, {
title,
icon
}) {
(0, _data.dispatch)(_store.store).addBlockCollection(namespace, title, icon);
}
/**
* Unregisters a block collection
*
* @param {string} namespace The namespace to group blocks by in the inserter; corresponds to the block namespace
*
*/
function unregisterBlockCollection(namespace) {
(0, _data.dispatch)(_store.store).removeBlockCollection(namespace);
}
/**
* Unregisters a block.
*
* @param {string} name Block name.
*
* @return {?WPBlock} The previous block value, if it has been successfully
* unregistered; otherwise `undefined`.
*/
function unregisterBlockType(name) {
const oldBlock = (0, _data.select)(_store.store).getBlockType(name);
if (!oldBlock) {
console.error('Block "' + name + '" is not registered.');
return;
}
(0, _data.dispatch)(_store.store).removeBlockTypes(name);
return oldBlock;
}
/**
* Assigns name of block for handling non-block content.
*
* @param {string} blockName Block name.
*/
function setFreeformContentHandlerName(blockName) {
(0, _data.dispatch)(_store.store).setFreeformFallbackBlockName(blockName);
}
/**
* Retrieves name of block handling non-block content, or undefined if no
* handler has been defined.
*
* @return {?string} Block name.
*/
function getFreeformContentHandlerName() {
return (0, _data.select)(_store.store).getFreeformFallbackBlockName();
}
/**
* Retrieves name of block used for handling grouping interactions.
*
* @return {?string} Block name.
*/
function getGroupingBlockName() {
return (0, _data.select)(_store.store).getGroupingBlockName();
}
/**
* Assigns name of block handling unregistered block types.
*
* @param {string} blockName Block name.
*/
function setUnregisteredTypeHandlerName(blockName) {
(0, _data.dispatch)(_store.store).setUnregisteredFallbackBlockName(blockName);
}
/**
* Retrieves name of block handling unregistered block types, or undefined if no
* handler has been defined.
*
* @return {?string} Block name.
*/
function getUnregisteredTypeHandlerName() {
return (0, _data.select)(_store.store).getUnregisteredFallbackBlockName();
}
/**
* Assigns the default block name.
*
* @param {string} name Block name.
*/
function setDefaultBlockName(name) {
(0, _data.dispatch)(_store.store).setDefaultBlockName(name);
}
/**
* Assigns name of block for handling block grouping interactions.
*
* @param {string} name Block name.
*/
function setGroupingBlockName(name) {
(0, _data.dispatch)(_store.store).setGroupingBlockName(name);
}
/**
* Retrieves the default block name.
*
* @return {?string} Block name.
*/
function getDefaultBlockName() {
return (0, _data.select)(_store.store).getDefaultBlockName();
}
/**
* Returns a registered block type.
*
* @param {string} name Block name.
*
* @return {?Object} Block type.
*/
function getBlockType(name) {
return (0, _data.select)(_store.store).getBlockType(name);
}
/**
* Returns all registered blocks.
*
* @return {Array} Block settings.
*/
function getBlockTypes() {
return (0, _data.select)(_store.store).getBlockTypes();
}
/**
* Returns the block support value for a feature, if defined.
*
* @param {(string|Object)} nameOrType Block name or type object
* @param {string} feature Feature to retrieve
* @param {*} defaultSupports Default value to return if not
* explicitly defined
*
* @return {?*} Block support value
*/
function getBlockSupport(nameOrType, feature, defaultSupports) {
return (0, _data.select)(_store.store).getBlockSupport(nameOrType, feature, defaultSupports);
}
/**
* Returns true if the block defines support for a feature, or false otherwise.
*
* @param {(string|Object)} nameOrType Block name or type object.
* @param {string} feature Feature to test.
* @param {boolean} defaultSupports Whether feature is supported by
* default if not explicitly defined.
*
* @return {boolean} Whether block supports feature.
*/
function hasBlockSupport(nameOrType, feature, defaultSupports) {
return (0, _data.select)(_store.store).hasBlockSupport(nameOrType, feature, defaultSupports);
}
/**
* Determines whether or not the given block is a reusable block. This is a
* special block type that is used to point to a global block stored via the
* API.
*
* @param {Object} blockOrType Block or Block Type to test.
*
* @return {boolean} Whether the given block is a reusable block.
*/
function isReusableBlock(blockOrType) {
return blockOrType.name === 'core/block';
}
/**
* Determines whether or not the given block is a template part. This is a
* special block type that allows composing a page template out of reusable
* design elements.
*
* @param {Object} blockOrType Block or Block Type to test.
*
* @return {boolean} Whether the given block is a template part.
*/
function isTemplatePart(blockOrType) {
return blockOrType.name === 'core/template-part';
}
/**
* Returns an array with the child blocks of a given block.
*
* @param {string} blockName Name of block (example: “latest-posts”).
*
* @return {Array} Array of child block names.
*/
const getChildBlockNames = blockName => {
return (0, _data.select)(_store.store).getChildBlockNames(blockName);
};
/**
* Returns a boolean indicating if a block has child blocks or not.
*
* @param {string} blockName Name of block (example: “latest-posts”).
*
* @return {boolean} True if a block contains child blocks and false otherwise.
*/
exports.getChildBlockNames = getChildBlockNames;
const hasChildBlocks = blockName => {
return (0, _data.select)(_store.store).hasChildBlocks(blockName);
};
/**
* Returns a boolean indicating if a block has at least one child block with inserter support.
*
* @param {string} blockName Block type name.
*
* @return {boolean} True if a block contains at least one child blocks with inserter support
* and false otherwise.
*/
exports.hasChildBlocks = hasChildBlocks;
const hasChildBlocksWithInserterSupport = blockName => {
return (0, _data.select)(_store.store).hasChildBlocksWithInserterSupport(blockName);
};
/**
* Registers a new block style variation for the given block.
*
* @param {string} blockName Name of block (example: “core/latest-posts”).
* @param {Object} styleVariation Object containing `name` which is the class name applied to the block and `label` which identifies the variation to the user.
*/
exports.hasChildBlocksWithInserterSupport = hasChildBlocksWithInserterSupport;
const registerBlockStyle = (blockName, styleVariation) => {
(0, _data.dispatch)(_store.store).addBlockStyles(blockName, styleVariation);
};
/**
* Unregisters a block style variation for the given block.
*
* @param {string} blockName Name of block (example: “core/latest-posts”).
* @param {string} styleVariationName Name of class applied to the block.
*/
exports.registerBlockStyle = registerBlockStyle;
const unregisterBlockStyle = (blockName, styleVariationName) => {
(0, _data.dispatch)(_store.store).removeBlockStyles(blockName, styleVariationName);
};
/**
* Returns an array with the variations of a given block type.
*
* @param {string} blockName Name of block (example: “core/columns”).
* @param {WPBlockVariationScope} [scope] Block variation scope name.
*
* @return {(WPBlockVariation[]|void)} Block variations.
*/
exports.unregisterBlockStyle = unregisterBlockStyle;
const getBlockVariations = (blockName, scope) => {
return (0, _data.select)(_store.store).getBlockVariations(blockName, scope);
};
/**
* Registers a new block variation for the given block type.
*
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {WPBlockVariation} variation Object describing a block variation.
*/
exports.getBlockVariations = getBlockVariations;
const registerBlockVariation = (blockName, variation) => {
(0, _data.dispatch)(_store.store).addBlockVariations(blockName, variation);
};
/**
* Unregisters a block variation defined for the given block type.
*
* @param {string} blockName Name of the block (example: “core/columns”).
* @param {string} variationName Name of the variation defined for the block.
*/
exports.registerBlockVariation = registerBlockVariation;
const unregisterBlockVariation = (blockName, variationName) => {
(0, _data.dispatch)(_store.store).removeBlockVariations(blockName, variationName);
};
exports.unregisterBlockVariation = unregisterBlockVariation;
//# sourceMappingURL=registration.js.map