Skip to content

Commit

Permalink
Feat: Adds JSDoc for query block.
Browse files Browse the repository at this point in the history
  • Loading branch information
Anuj-Rathore24 committed Jan 23, 2025
1 parent 0d35e9f commit 2721092
Showing 10 changed files with 141 additions and 0 deletions.
12 changes: 12 additions & 0 deletions packages/block-library/src/query-pagination-next/edit.js
Original file line number Diff line number Diff line change
@@ -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,
16 changes: 16 additions & 0 deletions packages/block-library/src/query-pagination-numbers/edit.js
Original file line number Diff line number Diff line change
@@ -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,
13 changes: 13 additions & 0 deletions packages/block-library/src/query-pagination-previous/edit.js
Original file line number Diff line number Diff line change
@@ -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,
11 changes: 11 additions & 0 deletions packages/block-library/src/query-pagination/edit.js
Original file line number Diff line number Diff line change
@@ -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,
11 changes: 11 additions & 0 deletions packages/block-library/src/query/edit/enhanced-pagination-modal.js
Original file line number Diff line number Diff line change
@@ -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 },
9 changes: 9 additions & 0 deletions packages/block-library/src/query/edit/index.js
Original file line number Diff line number Diff line change
@@ -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 ] =
29 changes: 29 additions & 0 deletions packages/block-library/src/query/edit/pattern-selection.js
Original file line number Diff line number Diff line change
@@ -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,
12 changes: 12 additions & 0 deletions packages/block-library/src/query/edit/query-content.js
Original file line number Diff line number Diff line change
@@ -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,
20 changes: 20 additions & 0 deletions packages/block-library/src/query/edit/query-placeholder.js
Original file line number Diff line number Diff line change
@@ -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 );
8 changes: 8 additions & 0 deletions packages/block-library/src/query/edit/query-toolbar.js
Original file line number Diff line number Diff line change
@@ -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 ) {

0 comments on commit 2721092

Please sign in to comment.