@wordpress/block-library 10.4.0 → 10.5.2-next.v.202608281122.0

package/src/avatar/{edit.js → edit.jsx}

@@ -17,6 +17,17 @@ import { useToolsPanelDropdownMenuProps } from '../utils/hooks';
 import { useCommentAvatar, useUserAvatar } from './hooks';
 import UserControl from './user-control';
 
+/**
+ * Renders the inspector controls for the `core/avatar` block.
+ *
+ * @param {Object}   props               React props.
+ * @param {Function} props.setAttributes Callback for updating block attributes.
+ * @param {Object}   props.avatar        Avatar data returned by `useCommentAvatar` or `useUserAvatar`, with the `minSize` and `maxSize` bounds of the size control.
+ * @param {Object}   props.attributes    Block attributes: `size`, `isLink`, `linkTarget` and `userId`.
+ * @param {boolean}  props.selectUser    Whether to render the user selection control.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 const AvatarInspectorControls = ( {
 	setAttributes,
 	avatar,
@@ -115,6 +126,17 @@ const AvatarInspectorControls = ( {
 	);
 };
 
+/**
+ * Wraps the avatar image in a placeholder link when the block links to the user
+ * profile. The link is inert in the editor: it points at a fragment and its
+ * click handler prevents navigation.
+ *
+ * @param {Object}          props          React props.
+ * @param {React.ReactNode} props.children Avatar image to wrap.
+ * @param {boolean}         props.isLink   Whether to wrap the children in a link.
+ *
+ * @return {React.ReactNode} The children, wrapped in a link when `isLink` is true.
+ */
 const AvatarLinkWrapper = ( { children, isLink } ) =>
 	isLink ? (
 		<a
@@ -128,6 +150,19 @@ const AvatarLinkWrapper = ( { children, isLink } ) =>
 		children
 	);
 
+/**
+ * Renders the avatar image inside a `ResizableBox` so its size can be adjusted
+ * by dragging. Resizing keeps the aspect ratio and updates the `size` attribute.
+ *
+ * @param {Object}   props               React props.
+ * @param {Function} props.setAttributes Callback for updating block attributes.
+ * @param {Object}   props.attributes    Block attributes: `size` and `isLink`, plus the border support values read by `useBorderProps`.
+ * @param {Object}   props.avatar        Avatar data returned by `useCommentAvatar` or `useUserAvatar`, with the image `src` and `alt` and the `minSize` and `maxSize` resize bounds.
+ * @param {Object}   props.blockProps    Props returned by `useBlockProps`, applied to the wrapper element.
+ * @param {boolean}  props.isSelected    Whether the block is selected. Resize handles are only shown when it is.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 const ResizableAvatar = ( {
 	setAttributes,
 	attributes,
@@ -187,6 +222,20 @@ const ResizableAvatar = ( {
 		</div>
 	);
 };
+
+/**
+ * Renders the block for a comment author, resolving the avatar from the
+ * `commentId` context. The user selection control is not offered here because
+ * the author is determined by the comment.
+ *
+ * @param {Object}   props               React props.
+ * @param {Object}   props.attributes    Block attributes.
+ * @param {Object}   props.context       Inherited context, from which the comment ID is read.
+ * @param {Function} props.setAttributes Callback for updating block attributes.
+ * @param {boolean}  props.isSelected    Whether the block is selected.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 const CommentEdit = ( { attributes, context, setAttributes, isSelected } ) => {
 	const { commentId } = context;
 	const blockProps = useBlockProps();
@@ -210,6 +259,19 @@ const CommentEdit = ( { attributes, context, setAttributes, isSelected } ) => {
 	);
 };
 
+/**
+ * Renders the block for a user, resolving the avatar from the `userId`
+ * attribute when set, and otherwise from the author of the post identified by
+ * the `postType` and `postId` context.
+ *
+ * @param {Object}   props               React props.
+ * @param {Object}   props.attributes    Block attributes, from which the `userId` is read.
+ * @param {Object}   props.context       Inherited context, from which the post type and post ID are read.
+ * @param {Function} props.setAttributes Callback for updating block attributes.
+ * @param {boolean}  props.isSelected    Whether the block is selected.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => {
 	const { postId, postType } = context;
 	const avatar = useUserAvatar( {
@@ -238,6 +300,22 @@ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => {
 	);
 };
 
+/**
+ * Renders the `core/avatar` block on the editor. All props are forwarded to
+ * either `CommentEdit` or `UserEdit`, depending on whether the block is used
+ * inside a comment.
+ *
+ * @param {Object}      props                     React props.
+ * @param {Object}      props.attributes          Block attributes.
+ * @param {Object}      props.context             Inherited context.
+ * @param {number|null} [props.context.commentId] The comment ID when the block is used inside a comment. `null` in the Site Editor, where no comment is resolved but the comment variant is still rendered.
+ * @param {string}      [props.context.postType]  The post type of the current post.
+ * @param {number}      [props.context.postId]    The ID of the current post.
+ * @param {Function}    props.setAttributes       Callback for updating block attributes.
+ * @param {boolean}     props.isSelected          Whether the block is selected.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 export default function Edit( props ) {
 	// Don't show the Comment Edit controls if we have a comment ID set, or if we're in the Site Editor (where it is `null`).
 	if ( props?.context?.commentId || props?.context?.commentId === null ) {

package/src/block/README.md

@@ -29,6 +29,7 @@ _Defined via the [`supports`](https://developer.wordpress.org/block-editor/refer
 - [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
   - `clientNavigation`: `true`
 - `customCSS`: `false`
+- [`visibility`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#visibility): `false`
 
 ## Context
 
@@ -51,6 +52,6 @@ In post content, it is stored as a block comment:
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/block/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/block/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/block/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/block/block.json

@@ -27,6 +27,7 @@
 		"interactivity": {
 			"clientNavigation": true
 		},
-		"customCSS": false
+		"customCSS": false,
+		"visibility": false
 	}
 }

package/src/breadcrumbs/README.md

@@ -62,6 +62,6 @@ In post content, it is stored as a block comment:
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/breadcrumbs/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/breadcrumbs/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/breadcrumbs/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/button/README.md

@@ -88,6 +88,6 @@ This is a [**hybrid block**](https://developer.wordpress.org/block-editor/gettin
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/button/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/button/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/button/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/buttons/README.md

@@ -75,6 +75,6 @@ This is a [**static block**](https://developer.wordpress.org/block-editor/gettin
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/buttons/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/buttons/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/buttons/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/calendar/README.md

@@ -46,6 +46,6 @@ In post content, it is stored as a block comment:
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/calendar/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/calendar/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/calendar/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/categories/README.md

@@ -64,6 +64,6 @@ In post content, it is stored as a block comment:
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/categories/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/categories/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/categories/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/categories/style.scss

@@ -14,8 +14,8 @@
 	&.wp-block-categories-dropdown.aligncenter {
 		text-align: center;
 	}
-	& .wp-block-categories__label:not(.screen-reader-text) {
-		width: 100%;
-		display: block;
-	}
+}
+:where(.wp-block-categories__label:not(.screen-reader-text)) {
+	width: 100%;
+	display: block;
 }

package/src/code/README.md

@@ -50,6 +50,6 @@ This is a [**static block**](https://developer.wordpress.org/block-editor/gettin
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/code/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/code/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/code/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/column/README.md

@@ -67,6 +67,6 @@ This is a [**static block**](https://developer.wordpress.org/block-editor/gettin
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/column/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/column/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/column/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/column/{edit.js → edit.jsx}

@@ -55,6 +55,20 @@ function ColumnInspectorControls( { width, setAttributes } ) {
 	);
 }
 
+/**
+ * Renders the `core/column` block in the editor.
+ *
+ * @param {Object}         props                                Component props.
+ * @param {Object}         props.attributes                     Block attributes.
+ * @param {string}         [props.attributes.verticalAlignment] Vertical alignment of the column, one of `top`, `center`, `bottom` or `stretch`. Setting it resets the alignment on the parent Columns block.
+ * @param {string|number}  [props.attributes.width]             Column width, used as its `flex-basis`. A number is treated as a percentage, for content saved before the attribute became a CSS length.
+ * @param {string|boolean} [props.attributes.templateLock]      Template lock applied to the inner blocks, one of `all`, `insert`, `contentOnly` or `false`.
+ * @param {string[]}       [props.attributes.allowedBlocks]     Names of the blocks allowed as inner blocks, added by the `allowedBlocks` block support.
+ * @param {Function}       props.setAttributes                  Callback for updating block attributes.
+ * @param {string}         props.clientId                       Client ID of the block.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 function ColumnEdit( {
 	attributes: { verticalAlignment, width, templateLock, allowedBlocks },
 	setAttributes,
@@ -113,7 +127,7 @@ function ColumnEdit( {
 			templateLock,
 			allowedBlocks,
 			renderAppender: hasChildBlocks
-				? undefined
+				? false
 				: InnerBlocks.ButtonBlockAppender,
 		}
 	);

package/src/columns/README.md

@@ -85,6 +85,6 @@ This is a [**static block**](https://developer.wordpress.org/block-editor/gettin
 ## Source
 
 - [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/columns/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
-- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/columns/) — browse `edit.js`, `save.js`, `index.php`, and more.
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/columns/) — browse the `edit` and `save` source files, `index.php`, and more.
 
 <!-- END TOKEN(Autogenerated block API docs) -->

package/src/columns/{edit.js → edit.jsx}

@@ -294,6 +294,24 @@ function Placeholder( { clientId, name, setAttributes } ) {
 	);
 }
 
+/**
+ * Renders the `core/columns` block in the editor.
+ *
+ * Until the block has inner blocks it renders a variation picker; afterwards it
+ * renders the columns container. Every prop is forwarded to whichever of the two
+ * is rendered.
+ *
+ * @param {Object}         props                                Component props.
+ * @param {string}         props.clientId                       Client ID of the block.
+ * @param {string}         props.name                           Block name, used to look up the variations offered by the picker.
+ * @param {Object}         props.attributes                     Block attributes.
+ * @param {string}         [props.attributes.verticalAlignment] Vertical alignment applied to the block and to every child Column block.
+ * @param {boolean}        [props.attributes.isStackedOnMobile] Whether the columns stack on small viewports. Defaults to `true`.
+ * @param {string|boolean} [props.attributes.templateLock]      Template lock applied to the inner blocks, one of `all`, `insert`, `contentOnly` or `false`.
+ * @param {Function}       props.setAttributes                  Callback for updating block attributes.
+ *
+ * @return {React.JSX.Element} React element.
+ */
 const ColumnsEdit = ( props ) => {
 	const { clientId } = props;
 	const hasInnerBlocks = useSelect(