Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Gallery block: add docblock comments to the new gallery hooks #34562

Merged
merged 1 commit into from
Sep 7, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions packages/block-library/src/gallery/use-get-media.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ import { useState } from '@wordpress/element';
import { useSelect } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

/**
* Retrieves the extended media info for each gallery image from the store. This is used to
* determine which image size options are available for the current gallery.
*
* @param {Array} innerBlockImages An array of the innerBlock images currently in the gallery.
*
* @return {Array} An array of media info options for each gallery image.
*/
export default function useGetMedia( innerBlockImages ) {
const [ currentImageMedia, setCurrentImageMedia ] = useState( [] );

Expand Down
10 changes: 10 additions & 0 deletions packages/block-library/src/gallery/use-get-new-images.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,16 @@
*/
import { useMemo, useState } from '@wordpress/element';

/**
* Keeps track of images already in the gallery to allow new innerBlocks to be identified. This
* is required so default gallery attributes can be applied without overwriting any custom
* attributes applied to existing images.
*
* @param {Array} images Basic image block data taken from current gallery innerBlock
* @param {Array} imageData The related image data for each of the current gallery images.
*
* @return {Array} An array of any new images that have been added to the gallery.
*/
export default function useGetNewImages( images, imageData ) {
const [ currentImages, setCurrentImages ] = useState( [] );

Expand Down
10 changes: 10 additions & 0 deletions packages/block-library/src/gallery/use-image-sizes.js
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,16 @@ import { get, some } from 'lodash';
*/
import { useMemo } from '@wordpress/element';

/**
* Calculates the image sizes that are avaible for the current gallery images in order to
* populate the 'Image size' selector.
*
* @param {Array} images Basic image block data taken from current gallery innerBlock
* @param {boolean} isSelected Is the block currently selected in the editor.
* @param {Function} getSettings Block editor store selector.
*
* @return {Array} An array of image size options.
*/
export default function useImageSizes( images, isSelected, getSettings ) {
return useMemo( () => getImageSizing(), [ images, isSelected ] );

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ import { every } from 'lodash';
import { useSelect } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

/**
* Shortcode transforms don't currently have a tranform method and so can't use a selector to
* retrieve the data for each image being transformer, so this selector handle this post transformation.
*
* @param {Array} shortCodeTransforms An array of image data passed from the shortcode transform.
*
* @return {Array} An array of extended image data objects for each of the shortcode transform images.
*/
export default function useShortCodeTransform( shortCodeTransforms ) {
const newImageData = useSelect(
( select ) => {
Expand Down