diff --git a/packages/block-library/src/query-pagination-next/edit.js b/packages/block-library/src/query-pagination-next/edit.js index 2bd38277a4b6c..0d3994dab0a4f 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 a03ed8419bb08..a0d4a50701d43 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 b32f15052f2e6..c28e597afe624 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 8ca0705058be2..075348630865f 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/edit/enhanced-pagination-modal.js b/packages/block-library/src/query/edit/enhanced-pagination-modal.js index 332cc337bb0f6..872b15f4093f7 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 60fc2ebd6170b..9d78db322ce54 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/pattern-selection.js b/packages/block-library/src/query/edit/pattern-selection.js index 0c5d95d15206f..e8f94f33da9a0 100644 --- a/packages/block-library/src/query/edit/pattern-selection.js +++ b/packages/block-library/src/query/edit/pattern-selection.js @@ -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, diff --git a/packages/block-library/src/query/edit/query-content.js b/packages/block-library/src/query/edit/query-content.js index 459ce2af018c2..92a9683ad18e2 100644 --- a/packages/block-library/src/query/edit/query-content.js +++ b/packages/block-library/src/query/edit/query-content.js @@ -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, diff --git a/packages/block-library/src/query/edit/query-placeholder.js b/packages/block-library/src/query/edit/query-placeholder.js index c3a01a0447f55..375050183c160 100644 --- a/packages/block-library/src/query/edit/query-placeholder.js +++ b/packages/block-library/src/query/edit/query-placeholder.js @@ -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 ); diff --git a/packages/block-library/src/query/edit/query-toolbar.js b/packages/block-library/src/query/edit/query-toolbar.js index 25e087ebe1559..66cbd3a97b6bb 100644 --- a/packages/block-library/src/query/edit/query-toolbar.js +++ b/packages/block-library/src/query/edit/query-toolbar.js @@ -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 ) {