WordPress · Anuj-Rathore24 · Jan 23, 2025 · Jan 24, 2025
@@ -10,6 +10,18 @@ const arrowMap = {
 	chevron: '»',
 };
 
+/*
+ * QueryPaginationNextEdit component provides the block editor interface for editing the "Next" pagination link.
+ *
+ * @param {Object} props                               Component props.
+ * @param {Object} props.attributes                    Block attributes.
+ * @param {string} props.attributes.label              The label text for the "Next" pagination link.
+ * @param {Function} props.setAttributes               Function to update block attributes.
+ * @param {Object} props.context                       Contextual data passed to the block.
+ * @param {string} props.context.paginationArrow       Type of arrow to display for pagination (e.g., 'none', 'arrow').
+ * @param {boolean} props.context.showLabel            Determines whether the label text is shown.
+ * @return {JSX.Element}                               The rendered block editor interface for the "Next" pagination link.
+ */
 export default function QueryPaginationNextEdit( {
 	attributes: { label },
 	setAttributes,

@@ -20,6 +20,12 @@ const createPaginationItem = ( content, Tag = 'a', extraClass = '' ) => (
 	</Tag>
 );
 
+/*
+ * Generates a preview of pagination numbers based on the specified mid-size value.
+ *
+ * @param {number} midSize The number of links to display before and after the current page.
+ * @return {JSX.Element} A JSX fragment containing the pagination items.
+ */
 const previewPaginationNumbers = ( midSize ) => {
 	const paginationItems = [];
 
@@ -47,6 +53,16 @@ const previewPaginationNumbers = ( midSize ) => {
 	return <>{ paginationItems }</>;
 };
 
+/*
+ * QueryPaginationNumbersEdit component provides the block editor interface
+ * for editing the pagination numbers display.
+ *
+ * @param {Object} props                    		Component props.
+ * @param {Object} props.attributes         		Block attributes.
+ * @param {number} props.attributes.midSize 		The number of links before and after the current page.
+ * @param {Function} props.setAttributes    		Function to update block attributes.
+ * @return {JSX.Element} 							The rendered block editor interface for pagination numbers.
+ */
 export default function QueryPaginationNumbersEdit( {
 	attributes,
 	setAttributes,

@@ -10,6 +10,19 @@ const arrowMap = {
 	chevron: '«',
 };
 
+/*
+ * QueryPaginationPreviousEdit component provides the block editor interface
+ * for editing the "Previous Page" pagination link.
+ *
+ * @param {Object} props                        	Component props.
+ * @param {Object} props.attributes             	Block attributes.
+ * @param {string} props.attributes.label       	The label displayed for the "Previous Page" link.
+ * @param {Function} props.setAttributes        	Function to update block attributes.
+ * @param {Object} props.context                	Block context.
+ * @param {string} props.context.paginationArrow 	The type of arrow to display (e.g., left arrow).
+ * @param {boolean} props.context.showLabel     	Whether to display the label for the pagination link.
+ * @return {JSX.Element} 							The rendered block editor interface for the "Previous Page" link.
+ */
 export default function QueryPaginationPreviousEdit( {
 	attributes: { label },
 	setAttributes,

@@ -28,6 +28,17 @@ const TEMPLATE = [
 	[ 'core/query-pagination-next' ],
 ];
 
+/*
+ * QueryPaginationEdit component provides the block editor interface for editing pagination settings.
+ *
+ * @param {Object} props                              	Component props.
+ * @param {Object} props.attributes                  	Block attributes.
+ * @param {string} props.attributes.paginationArrow  	Defines the type of arrow to display for pagination (e.g., 'none', 'arrow').
+ * @param {boolean} props.attributes.showLabel       	Determines whether label text is shown with pagination.
+ * @param {Function} props.setAttributes             	Function to update block attributes.
+ * @param {string} props.clientId                    	The client ID of the block.
+ * @return {JSX.Element}                             	The rendered block editor interface.
+ */
 export default function QueryPaginationEdit( {
 	attributes: { paginationArrow, showLabel },
 	setAttributes,

@@ -29,6 +29,21 @@ import { useToolsPanelDropdownMenuProps } from '../utils/hooks';
 
 const SUPPORTED_TYPES = [ 'archive', 'search' ];
 
+/*
+ * QueryTitleEdit component provides the block editor interface for rendering and editing the title
+ * of a query-based block, such as archive titles or search result titles.
+ *
+ * @param {Object} props                        		Component props.
+ * @param {Object} props.attributes             		Block attributes.
+ * @param {string} props.attributes.type        		The type of query (e.g., 'archive' or 'search').
+ * @param {number} props.attributes.level       		The heading level for the title (e.g., 1 for `<h1>`).
+ * @param {Array}  props.attributes.levelOptions 		Available heading level options.
+ * @param {string} props.attributes.textAlign   		Text alignment for the title (e.g., 'left', 'center').
+ * @param {boolean} props.attributes.showPrefix 		Whether to show the archive type prefix (e.g., 'Category:').
+ * @param {boolean} props.attributes.showSearchTerm 	Whether to show the search term in the title.
+ * @param {Function} props.setAttributes        		Function to update block attributes.
+ * @return {JSX.Element} 								The rendered block editor interface for the query title.
+ */
 export default function QueryTitleEdit( {
 	attributes: {
 		type,

@@ -10,6 +10,16 @@ import { __ } from '@wordpress/i18n';
  */
 import { resultsFound, displayingResults } from './icons';
 
+/*
+ * QueryTotalEdit component provides the block editor interface for rendering and editing
+ * the total query results or a range display for query results.
+ *
+ * @param {Object} props                        	Component props.
+ * @param {Object} props.attributes             	Block attributes.
+ * @param {string} props.attributes.displayType 	The selected display type ('total-results' or 'range-display').
+ * @param {Function} props.setAttributes        	Function to update block attributes.
+ * @return {JSX.Element} 							The rendered block editor interface for the query total display.
+ */
 export default function QueryTotalEdit( { attributes, setAttributes } ) {
 	const { displayType } = attributes;
 

@@ -17,6 +17,17 @@ import { useUnsupportedBlocks } from '../utils';
 const modalDescriptionId =
 	'wp-block-query-enhanced-pagination-modal__description';
 
+/*
+ * EnhancedPaginationModal - Renders a modal for handling enhanced pagination settings in the Query block.
+ *
+ * @param {Object} props                          			The component properties.
+ * @param {string} props.clientId                 			The client ID of the Query block.
+ * @param {Object} props.attributes               			The attributes of the Query block.
+ * @param {boolean} props.attributes.enhancedPagination 	Whether enhanced pagination is enabled.
+ * @param {Function} props.setAttributes          			Function to update block attributes.
+ *
+ * @returns {JSX.Element|null} 								The rendered modal if conditions are met; otherwise, null.
+ */
 export default function EnhancedPaginationModal( {
 	clientId,
 	attributes: { enhancedPagination },

@@ -12,6 +12,15 @@ import QueryContent from './query-content';
 import QueryPlaceholder from './query-placeholder';
 import { PatternSelectionModal } from './pattern-selection';
 
+/*
+ * QueryEdit - The edit component for the Query block in the WordPress block editor.
+ *
+ * @param {Object} props                    The component properties.
+ * @param {string} props.clientId           The unique client ID of the Query block.
+ * @param {Object} props.attributes         The attributes of the Query block.
+ *
+ * @returns {JSX.Element} 					The rendered Query block edit interface.
+ */
 const QueryEdit = ( props ) => {
 	const { clientId, attributes } = props;
 	const [ isPatternSelectionModalOpen, setIsPatternSelectionModalOpen ] =

@@ -18,6 +18,14 @@ const AUTHORS_QUERY = {
 	context: 'view',
 };
 
+/*
+ * AuthorControl component for managing and selecting authors.
+ *
+ * @param {Object} props         		Component props.
+ * @param {string} props.value   		Comma-separated string of selected author IDs.
+ * @param {Function} props.onChange 	Callback function to handle changes in selected authors.
+ * @return {JSX.Element|null} 			The rendered AuthorControl component or null if no authors are available.
+ */
 function AuthorControl( { value, onChange } ) {
 	const authorsList = useSelect( ( select ) => {
 		const { getUsers } = select( coreStore );

@@ -9,6 +9,15 @@ import { __ } from '@wordpress/i18n';
  */
 import { useUnsupportedBlocks } from '../../utils';
 
+/*
+ * EnhancedPaginationControl component for managing the pagination behavior.
+ *
+ * @param {Object} props                          	Component props.
+ * @param {boolean} props.enhancedPagination      	Indicates whether enhanced pagination is enabled.
+ * @param {Function} props.setAttributes          	Callback function to update block attributes.
+ * @param {string} props.clientId                 	The client ID of the block.
+ * @return {JSX.Element} 							The rendered EnhancedPaginationControl component.
+ */
 export default function EnhancedPaginationControl( {
 	enhancedPagination,
 	setAttributes,

@@ -32,7 +32,13 @@ const POST_FORMATS = [
 	return 0;
 } );
 
-// A helper function to convert translatable post format names into their static values.
+/*
+ * A helper function to convert translatable post format names into their static values.
+ *
+ * @param {string[]} names   	Array of format names (translatable labels).
+ * @param {Object[]} formats 	Array of format objects with `label` and `value` properties.
+ * @return {string[]} 			Array of format values corresponding to the provided names.
+ */
 function formatNamesToValues( names, formats ) {
 	return names
 		.map( ( name ) => {
@@ -44,6 +50,15 @@ function formatNamesToValues( names, formats ) {
 		.filter( Boolean );
 }
 
+/*
+ * FormatControls component for managing and selecting post formats.
+ *
+ * @param {Object} props                    		Component props.
+ * @param {Function} props.onChange         		Callback function to handle changes in selected formats.
+ * @param {Object} props.query              		Query object containing format information.
+ * @param {string|string[]} props.query.format 		The current selected format(s), either as a string or an array.
+ * @return {JSX.Element} 							The rendered FormatControls component.
+ */
 export default function FormatControls( { onChange, query: { format } } ) {
 	// 'format' is expected to be an array. If it is not an array, for example
 	// if a user has manually entered an invalid value in the block markup,

@@ -7,6 +7,14 @@ import { __ } from '@wordpress/i18n';
 const MIN_OFFSET = 0;
 const MAX_OFFSET = 100;
 
+/*
+ * OffsetControl component for adjusting the offset value.
+ *
+ * @param {Object} props            	Component props.
+ * @param {number} [props.offset=0] 	Current offset value. Defaults to 0 if not provided.
+ * @param {Function} props.onChange 	Callback function to handle changes to the offset value.
+ * @return {JSX.Element} 				The rendered OffsetControl component.
+ */
 export const OffsetControl = ( { offset = 0, onChange } ) => {
 	return (
 		<NumberControl

@@ -21,6 +21,16 @@ import {
 } from '../utils';
 import { searchPatterns } from '../../utils/search-patterns';
 
+/*
+ * Renders a modal for selecting a block pattern.
+ *
+ * @param {Object} props                               		Component properties.
+ * @param {string} props.clientId                      		The client ID of the block.
+ * @param {Object} props.attributes                    		The attributes of the block.
+ * @param {Function} props.setIsPatternSelectionModalOpen 	Function to toggle the modal state.
+ *
+ * @returns {JSX.Element} 									The rendered Pattern Selection Modal.
+ */
 export function PatternSelectionModal( {
 	clientId,
 	attributes,
@@ -38,6 +48,14 @@ export function PatternSelectionModal( {
 	);
 }
 
+/*
+ * Hook to retrieve block patterns based on the block's client ID and attributes.
+ *
+ * @param {string} clientId     The client ID of the block.
+ * @param {Object} attributes   The attributes of the block.
+ *
+ * @returns {Array} 			An array of block patterns.
+ */
 export function useBlockPatterns( clientId, attributes ) {
 	const blockNameForPatterns = useBlockNameForPatterns(
 		clientId,
@@ -46,6 +64,17 @@ export function useBlockPatterns( clientId, attributes ) {
 	return usePatterns( clientId, blockNameForPatterns );
 }
 
+/*
+ * Component for displaying and selecting block patterns.
+ *
+ * @param {Object} props                          	Component properties.
+ * @param {string} props.clientId                 	The client ID of the block.
+ * @param {Object} props.attributes               	The attributes of the block.
+ * @param {boolean} [props.showTitlesAsTooltip]   	Whether to show titles as tooltips (default: false).
+ * @param {boolean} [props.showSearch]            	Whether to show the search bar (default: true).
+ *
+ * @returns {JSX.Element} 							The rendered pattern selection interface.
+ */
 export default function PatternSelection( {
 	clientId,
 	attributes,

@@ -28,6 +28,18 @@ import { htmlElementMessages } from '../../utils/messages';
 const DEFAULTS_POSTS_PER_PAGE = 3;
 
 const TEMPLATE = [ [ 'core/post-template' ] ];
+
+/*
+ * QueryContent component for managing and rendering query-related block content.
+ *
+ * @param {Object}   props 							Component props.
+ * @param {Object}   props.attributes 				Block attributes.
+ * @param {Function} props.setAttributes 			Function to update block attributes.
+ * @param {string}   props.clientId 				The client ID of the block.
+ * @param {Object}   props.context 					Context data for the block.
+ * @param {string}   props.name 					The block name.
+ * @return {JSX.Element} 							The rendered QueryContent component.
+ */
 export default function QueryContent( {
 	attributes,
 	setAttributes,

@@ -21,6 +21,16 @@ import { __ } from '@wordpress/i18n';
 import { useScopedBlockVariations } from '../utils';
 import { useBlockPatterns } from './pattern-selection';
 
+/*
+ * QueryPlaceholder component for rendering a placeholder with options to choose a pattern or start blank.
+ *
+ * @param {Object}   props 								Component props.
+ * @param {Object}   props.attributes 					Block attributes.
+ * @param {string}   props.clientId 					The client ID of the block.
+ * @param {string}   props.name 						The block name.
+ * @param {Function} props.openPatternSelectionModal 	Function to open the pattern selection modal.
+ * @return {JSX.Element} 								The rendered QueryPlaceholder component.
+ */
 export default function QueryPlaceholder( {
 	attributes,
 	clientId,
@@ -92,6 +102,16 @@ export default function QueryPlaceholder( {
 	);
 }
 
+/*
+ * QueryVariationPicker component for selecting a block variation.
+ *
+ * @param {Object}   props 						Component props.
+ * @param {string}   props.clientId 			The client ID of the block.
+ * @param {Object}   props.attributes 			Block attributes.
+ * @param {string}   props.icon 				Icon for the variation picker.
+ * @param {string}   props.label 				Label for the variation picker.
+ * @return {JSX.Element} 						The rendered QueryVariationPicker component.
+ */
 function QueryVariationPicker( { clientId, attributes, icon, label } ) {
 	const scopeVariations = useScopedBlockVariations( attributes );
 	const { replaceInnerBlocks } = useDispatch( blockEditorStore );

@@ -14,6 +14,14 @@ import { __ } from '@wordpress/i18n';
  */
 import PatternSelection, { useBlockPatterns } from './pattern-selection';
 
+/*
+ * QueryToolbar component renders a toolbar for selecting and changing design patterns.
+ *
+ * @param {Object} props                     Component props.
+ * @param {string} props.clientId            The client ID of the block.
+ * @param {Object} props.attributes          The block attributes.
+ * @return {JSX.Element|null}                The rendered toolbar or null if no patterns are available.
+ */
 export default function QueryToolbar( { clientId, attributes } ) {
 	const hasPatterns = useBlockPatterns( clientId, attributes ).length;
 	if ( ! hasPatterns ) {