From c79a28d84a63ce01105d5f014d15841ac66fa67f Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Thu, 5 Dec 2024 16:52:40 +0000 Subject: [PATCH] feedback --- .../data/data-core-block-editor.md | 155 +++++++++--------- packages/block-editor/README.md | 124 +++++++------- 2 files changed, 140 insertions(+), 139 deletions(-) diff --git a/docs/reference-guides/data/data-core-block-editor.md b/docs/reference-guides/data/data-core-block-editor.md index 437f7be20f7705..9d3aaf6bed87ba 100644 --- a/docs/reference-guides/data/data-core-block-editor.md +++ b/docs/reference-guides/data/data-core-block-editor.md @@ -741,34 +741,34 @@ Returns the currently selected block, or null if there is no selected block. _Usage_ ```js -import { select } from '@wordpress/data'; -import { store as blockEditorStore } from '@wordpress/block-editor'; +import { select } from '@wordpress/data' +import { store as blockEditorStore } from '@wordpress/block-editor' // Set initial active block client ID -let activeBlockClientId = null; +let activeBlockClientId = null const getActiveBlockData = () => { - const activeBlock = select( blockEditorStore ).getSelectedBlock(); + const activeBlock = select(blockEditorStore).getSelectedBlock() - if ( activeBlock && activeBlock.clientId !== activeBlockClientId ) { - activeBlockClientId = activeBlock.clientId; + if (activeBlock && activeBlock.clientId !== activeBlockClientId) { + activeBlockClientId = activeBlock.clientId // Get active block name and attributes - const activeBlockName = activeBlock.name; - const activeBlockAttributes = activeBlock.attributes; + const activeBlockName = activeBlock.name + const activeBlockAttributes = activeBlock.attributes // Log active block name and attributes - console.log( activeBlockName, activeBlockAttributes ); + console.log(activeBlockName, activeBlockAttributes) + } } -}; -// Subscribe to changes in the editor -// wp.data.subscribe(() => { -// getActiveBlockData() -// }) + // Subscribe to changes in the editor + // wp.data.subscribe(() => { + // getActiveBlockData() + // }) -// Update active block data on click -// onclick="getActiveBlockData()" + // Update active block data on click + // onclick="getActiveBlockData()" ``` _Parameters_ @@ -869,7 +869,7 @@ Returns the defined block template _Parameters_ -- _state_ `boolean`: +- _state_ `boolean`: _Returns_ @@ -890,7 +890,7 @@ _Returns_ ### hasBlockMovingClientId -> **Deprecated** +> **Deprecated** Returns whether block moving mode is enabled. @@ -1092,7 +1092,7 @@ _Returns_ ### isCaretWithinFormattedText -> **Deprecated** +> **Deprecated** Returns true if the caret is within formatted text, or false otherwise. @@ -1221,7 +1221,7 @@ Returns whether the blocks matches the template or not. _Parameters_ -- _state_ `boolean`: +- _state_ `boolean`: _Returns_ @@ -1261,12 +1261,12 @@ Action that duplicates a list of blocks. _Parameters_ -- _clientIds_ `string[]`: -- _updateSelection_ `boolean`: +- _clientIds_ `string[]`: +- _updateSelection_ `boolean`: ### enterFormattedText -> **Deprecated** +> **Deprecated** Returns an action object used in signalling that the caret has entered formatted text. @@ -1276,7 +1276,7 @@ _Returns_ ### exitFormattedText -> **Deprecated** +> **Deprecated** Returns an action object used in signalling that the user caret has exited formatted text. @@ -1314,7 +1314,7 @@ Action that inserts a default block after a given block. _Parameters_ -- _clientId_ `string`: +- _clientId_ `string`: ### insertBeforeBlock @@ -1322,7 +1322,7 @@ Action that inserts a default block before a given block. _Parameters_ -- _clientId_ `string`: +- _clientId_ `string`: ### insertBlock @@ -1353,7 +1353,7 @@ _Parameters_ - _blocks_ `Object[]`: 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. +- _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. - _initialPosition_ `0|-1|null`: Initial focus position. Setting it to null prevent focusing the inserted block. - _meta_ `?Object`: Optional Meta values to be passed to the action object. @@ -1422,7 +1422,7 @@ _Parameters_ ### receiveBlocks -> **Deprecated** +> **Deprecated** 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. @@ -1466,54 +1466,54 @@ _Properties_ _Usage_ ```js -wp.data.dispatch( 'core/block-editor' ).registerInserterMediaCategory( { - name: 'openverse', - labels: { - name: 'Openverse', - search_items: 'Search Openverse', - }, - mediaType: 'image', - async fetch( query = {} ) { - const defaultArgs = { - mature: false, - excluded_source: 'flickr,inaturalist,wikimedia', - license: 'pdm,cc0', - }; - const finalQuery = { ...query, ...defaultArgs }; - // Sometimes you might need to map the supported request params according to `InserterMediaRequest`. - // interface. In this example the `search` query param is named `q`. - const mapFromInserterMediaRequest = { - per_page: 'page_size', - search: 'q', - }; - const url = new URL( 'https://api.openverse.org/v1/images/' ); - Object.entries( finalQuery ).forEach( ( [ key, value ] ) => { - const queryKey = mapFromInserterMediaRequest[ key ] || key; - url.searchParams.set( queryKey, value ); - } ); - const response = await window.fetch( url, { - headers: { - 'User-Agent': 'WordPress/inserter-media-fetch', - }, - } ); - const jsonResponse = await response.json(); - const results = jsonResponse.results; - return results.map( ( result ) => ( { - ...result, - // If your response result includes an `id` prop that you want to access later, it should - // be mapped to `InserterMediaItem`'s `sourceId` prop. This can be useful if you provide - // a report URL getter. - // Additionally you should always clear the `id` value of your response results because - // it is used to identify WordPress media items. - sourceId: result.id, - id: undefined, - caption: result.caption, - previewUrl: result.thumbnail, - } ) ); - }, - getReportUrl: ( { sourceId } ) => - `https://wordpress.org/openverse/image/${ sourceId }/report/`, - isExternalResource: true, +wp.data.dispatch('core/block-editor').registerInserterMediaCategory( { + name: 'openverse', + labels: { + name: 'Openverse', + search_items: 'Search Openverse', + }, + mediaType: 'image', + async fetch( query = {} ) { + const defaultArgs = { + mature: false, + excluded_source: 'flickr,inaturalist,wikimedia', + license: 'pdm,cc0', + }; + const finalQuery = { ...query, ...defaultArgs }; + // Sometimes you might need to map the supported request params according to `InserterMediaRequest`. + // interface. In this example the `search` query param is named `q`. + const mapFromInserterMediaRequest = { + per_page: 'page_size', + search: 'q', + }; + const url = new URL( 'https://api.openverse.org/v1/images/' ); + Object.entries( finalQuery ).forEach( ( [ key, value ] ) => { + const queryKey = mapFromInserterMediaRequest[ key ] || key; + url.searchParams.set( queryKey, value ); + } ); + const response = await window.fetch( url, { + headers: { + 'User-Agent': 'WordPress/inserter-media-fetch', + }, + } ); + const jsonResponse = await response.json(); + const results = jsonResponse.results; + return results.map( ( result ) => ( { + ...result, + // If your response result includes an `id` prop that you want to access later, it should + // be mapped to `InserterMediaItem`'s `sourceId` prop. This can be useful if you provide + // a report URL getter. + // Additionally you should always clear the `id` value of your response results because + // it is used to identify WordPress media items. + sourceId: result.id, + id: undefined, + caption: result.caption, + previewUrl: result.thumbnail, + } ) ); + }, + getReportUrl: ( { sourceId } ) => + `https://wordpress.org/openverse/image/${ sourceId }/report/`, + isExternalResource: true, } ); ``` @@ -1688,7 +1688,7 @@ _Returns_ ### setBlockMovingClientId -> **Deprecated** +> **Deprecated** Set the block moving client ID. @@ -1921,4 +1921,5 @@ _Parameters_ - _blocks_ `Array`: Array of blocks. + diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index a0f75683914408..6c4bb54171b371 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -121,16 +121,16 @@ _Usage_ ```jsx function MyBlockEditor() { - const [ blocks, updateBlocks ] = useState( [] ); - return ( - - - - ); + const [ blocks, updateBlocks ] = useState([]); + return ( + + + + ); } ``` @@ -159,7 +159,7 @@ _Related_ _Parameters_ -- _props_ `BlockContextProviderProps`: +- _props_ `BlockContextProviderProps`: ### BlockControls @@ -264,15 +264,12 @@ Renders the block's configured title as a string, or empty if the title cannot b _Usage_ ```jsx - + ``` _Parameters_ -- _props_ `Object`: +- _props_ `Object`: - _props.clientId_ `string`: Client ID of block. - _props.maximumLength_ `number|undefined`: The maximum length that the block title string may be before truncated. - _props.context_ `string|undefined`: The context to pass to `getBlockLabel`. @@ -325,7 +322,7 @@ _Related_ ### ButtonBlockerAppender -> **Deprecated** +> **Deprecated** Use `ButtonBlockAppender` instead. @@ -345,11 +342,11 @@ _Related_ ### CopyHandler -> **Deprecated** +> **Deprecated** _Parameters_ -- _props_ `Object`: +- _props_ `Object`: ### createCustomColorsHOC @@ -360,15 +357,12 @@ Use this higher-order component to work with a custom set of colors. _Usage_ ```jsx -const CUSTOM_COLORS = [ - { name: 'Red', slug: 'red', color: '#ff0000' }, - { name: 'Blue', slug: 'blue', color: '#0000ff' }, -]; +const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ]; const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS ); // ... export default compose( - withCustomColors( 'backgroundColor', 'borderColor' ), - MyColorfulComponent + withCustomColors( 'backgroundColor', 'borderColor' ), + MyColorfulComponent, ); ``` @@ -441,18 +435,18 @@ _Usage_ ```js // Calculate fluid font-size value from a minimum and maximum value. const fontSize = getComputedFluidTypographyValue( { - minimumFontSize: '20px', - maximumFontSize: '45px', + minimumFontSize: '20px', + maximumFontSize: '45px' } ); // Calculate fluid font-size value from a single font size. const fontSize = getComputedFluidTypographyValue( { - fontSize: '30px', + fontSize: '30px', } ); ``` _Parameters_ -- _args_ `Object`: +- _args_ `Object`: - _args.minimumViewportWidth_ `?string`: Minimum viewport size from which type will have fluidity. Optional if fontSize is specified. - _args.maximumViewportWidth_ `?string`: Maximum size up to which type will have fluidity. Optional if fontSize is specified. - _args.fontSize_ `[string|number]`: Size to derive maximumFontSize and minimumFontSize from, if necessary. Optional if minimumFontSize and maximumFontSize are specified. @@ -480,7 +474,7 @@ _Returns_ ### getFontSize -Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. + Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. _Parameters_ @@ -545,7 +539,7 @@ _Returns_ ### getPxFromCssUnit -> **Deprecated** +> **Deprecated** This function was accidentally exposed for mobile/native usage. @@ -600,7 +594,7 @@ _Related_ _Parameters_ -- _props_ `Object`: +- _props_ `Object`: - _props.label_ `?string`: A label for the control. - _props.onChange_ `( value: string ) => void`: Called when the height changes. - _props.value_ `string`: The current height value. @@ -685,7 +679,7 @@ _Related_ ### MultiSelectScrollIntoView -> **Deprecated** +> **Deprecated** Scrolls the multi block selection end into view if not in view already. This is important to do after selection by keyboard. @@ -721,7 +715,7 @@ Wrap block content with this provider and provide the same `uniqueId` prop as us _Parameters_ -- _props_ `Object`: +- _props_ `Object`: - _props.uniqueId_ `*`: Any value that acts as a unique identifier for a block instance. - _props.blockName_ `string`: Optional block name. - _props.children_ `JSX.Element`: React children. @@ -851,23 +845,23 @@ It contains the following utils: _Usage_ ```js -import { useBlockBindingsUtils } from '@wordpress/block-editor'; +import { useBlockBindingsUtils } from '@wordpress/block-editor' const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils(); // Update url and alt attributes. updateBlockBindings( { - url: { - source: 'core/post-meta', - args: { - key: 'url_custom_field', - }, - }, - alt: { - source: 'core/post-meta', - args: { - key: 'text_custom_field', - }, - }, + url: { + source: 'core/post-meta', + args: { + key: 'url_custom_field', + }, + }, + alt: { + source: 'core/post-meta', + args: { + key: 'text_custom_field', + }, + }, } ); // Remove binding from url attribute. @@ -923,8 +917,8 @@ _Usage_ ```js function MyBlock( { attributes, setAttributes } ) { - useBlockEditingMode( 'disabled' ); - return
; + useBlockEditingMode( 'disabled' ); + return
; } ``` @@ -961,15 +955,20 @@ _Usage_ import { useBlockProps } from '@wordpress/block-editor'; export default function Edit() { - const blockProps = useBlockProps( { - className: 'my-custom-class', - style: { - color: '#222222', - backgroundColor: '#eeeeee', - }, - } ); - - return
; + + const blockProps = useBlockProps( { + className: 'my-custom-class', + style: { + color: '#222222', + backgroundColor: '#eeeeee' + } + } ) + + return ( +
+ +
+ ) } ``` @@ -977,7 +976,7 @@ _Parameters_ - _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined. - _options_ `Object`: Options for internal use only. -- _options.\_\_unstableIsHtml_ `boolean`: +- _options.\_\_unstableIsHtml_ `boolean`: _Returns_ @@ -989,7 +988,7 @@ Keeps an up-to-date copy of the passed value and returns it. If value becomes fa _Parameters_ -- _value_ `any`: +- _value_ `any`: _Returns_ @@ -1095,8 +1094,8 @@ _Usage_ ```jsx export default compose( - withColors( 'backgroundColor', { textColor: 'color' } ), - MyColorfulComponent + withColors( 'backgroundColor', { textColor: 'color' } ), + MyColorfulComponent, ); ``` @@ -1129,6 +1128,7 @@ _Parameters_ - _props_ `Object`: Component properties. - _props.children_ `Element`: Children to be rendered. + ## Contributing to this package