diff --git a/packages/block-library/src/query-pagination-next/edit.js b/packages/block-library/src/query-pagination-next/edit.js index 2bd38277a4b6c0..0d3994dab0a4f1 100644 --- a/packages/block-library/src/query-pagination-next/edit.js +++ b/packages/block-library/src/query-pagination-next/edit.js @@ -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, diff --git a/packages/block-library/src/query-pagination-numbers/edit.js b/packages/block-library/src/query-pagination-numbers/edit.js index a03ed8419bb086..a0d4a50701d436 100644 --- a/packages/block-library/src/query-pagination-numbers/edit.js +++ b/packages/block-library/src/query-pagination-numbers/edit.js @@ -20,6 +20,12 @@ const createPaginationItem = ( content, Tag = 'a', extraClass = '' ) => ( ); +/* + * 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, diff --git a/packages/block-library/src/query-pagination-previous/edit.js b/packages/block-library/src/query-pagination-previous/edit.js index b32f15052f2e64..c28e597afe624d 100644 --- a/packages/block-library/src/query-pagination-previous/edit.js +++ b/packages/block-library/src/query-pagination-previous/edit.js @@ -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, diff --git a/packages/block-library/src/query-pagination/edit.js b/packages/block-library/src/query-pagination/edit.js index 8ca0705058be28..075348630865f8 100644 --- a/packages/block-library/src/query-pagination/edit.js +++ b/packages/block-library/src/query-pagination/edit.js @@ -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, diff --git a/packages/block-library/src/query-title/edit.js b/packages/block-library/src/query-title/edit.js index 0da6da47ef6147..e73a29faa22e08 100644 --- a/packages/block-library/src/query-title/edit.js +++ b/packages/block-library/src/query-title/edit.js @@ -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 `

`). + * @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, diff --git a/packages/block-library/src/query-total/edit.js b/packages/block-library/src/query-total/edit.js index d91a1990715727..e2d22703ffad9d 100644 --- a/packages/block-library/src/query-total/edit.js +++ b/packages/block-library/src/query-total/edit.js @@ -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; diff --git a/packages/block-library/src/query/edit/enhanced-pagination-modal.js b/packages/block-library/src/query/edit/enhanced-pagination-modal.js index 332cc337bb0f67..872b15f4093f78 100644 --- a/packages/block-library/src/query/edit/enhanced-pagination-modal.js +++ b/packages/block-library/src/query/edit/enhanced-pagination-modal.js @@ -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 }, diff --git a/packages/block-library/src/query/edit/index.js b/packages/block-library/src/query/edit/index.js index 60fc2ebd6170b3..9d78db322ce546 100644 --- a/packages/block-library/src/query/edit/index.js +++ b/packages/block-library/src/query/edit/index.js @@ -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 ] = diff --git a/packages/block-library/src/query/edit/inspector-controls/author-control.js b/packages/block-library/src/query/edit/inspector-controls/author-control.js index 4379dfe3e46cb6..94d1d7755d8511 100644 --- a/packages/block-library/src/query/edit/inspector-controls/author-control.js +++ b/packages/block-library/src/query/edit/inspector-controls/author-control.js @@ -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 ); diff --git a/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js b/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js index 4d0b1a9fd9da37..7bd7ac7825ae56 100644 --- a/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js +++ b/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js @@ -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, diff --git a/packages/block-library/src/query/edit/inspector-controls/format-controls.js b/packages/block-library/src/query/edit/inspector-controls/format-controls.js index 15c95f3bbba2e2..bff8bb8b5f771c 100644 --- a/packages/block-library/src/query/edit/inspector-controls/format-controls.js +++ b/packages/block-library/src/query/edit/inspector-controls/format-controls.js @@ -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, diff --git a/packages/block-library/src/query/edit/inspector-controls/offset-controls.js b/packages/block-library/src/query/edit/inspector-controls/offset-controls.js index ff755c95f8b0a9..c0436c12053565 100644 --- a/packages/block-library/src/query/edit/inspector-controls/offset-controls.js +++ b/packages/block-library/src/query/edit/inspector-controls/offset-controls.js @@ -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 (