@secretstache/wordpress-gutenberg 0.4.14 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secretstache/wordpress-gutenberg",
-  "version": "0.4.14",
+  "version": "0.5.1",
   "description": "",
   "author": "Secret Stache",
   "license": "GPL-2.0-or-later",

package/src/components/SpacingControl.js

@@ -27,7 +27,6 @@ const Control = ({ label, max, min, value, onChange, disabled, tooltip, ...other
                     max={max}
                     marks={generateMarks(min, max)}
                     resetFallbackValue={-1}
-                    help="Use -1 for default settings."
                     renderTooltipContent={(value) => {
                         if (value === -1) return 'Default';
 

package/src/hooks/useAllowedBlocks.js

@@ -20,6 +20,6 @@ export const useAllowedBlocks = (blockName, excludedBlocks) => {
                     && (!blockHasAncestor || isAncestor);
             })
             ?.map((block) => block.name),
-        [allBlocks, excludedBlocks, blockName],
+        [ allBlocks, excludedBlocks, blockName ],
     );
 };

package/src/utils/helpers.js

@@ -1,7 +1,18 @@
+import { filters } from '@wordpress/hooks';
 import apiFetch from '@wordpress/api-fetch';
 import slugify from 'slugify';
 import classNames from 'classnames';
+import { select, subscribe } from '@wordpress/data';
+import { getBlockType, unregisterBlockType } from '@wordpress/blocks';
 
+/**
+ * Loads select options by fetching posts from WordPress REST API.
+ * @async
+ * @param {string} inputValue - Search term to filter posts
+ * @param {string} postType - WordPress post type to query
+ * @param {Function|null} [mapper=null] - Optional function to transform API response items
+ * @returns {Promise<Array<{value: number, label: string}>>} Array of select options
+ */
 export const loadSelectOptions = async (inputValue, postType, mapper = null) => {
     const response = await apiFetch({
         path: `/wp/v2/${postType}?search=${encodeURIComponent(inputValue)}`,
@@ -23,12 +34,22 @@ export const loadSelectOptions = async (inputValue, postType, mapper = null) =>
     }
 };
 
+/**
+ * Converts a string to a URL-friendly slug.
+ * @param {string} name - String to convert to slug
+ * @returns {string} URL-friendly slug in lowercase with hyphens
+ */
 export const getSlug = (name) => slugify(name, {
     replacement: '-',
     lower: true,
     strict: true,
 });
 
+/**
+ * Cleans SVG string by removing XML declaration and extra whitespace.
+ * @param {string} svgString - Raw SVG string
+ * @returns {string} Cleaned SVG string
+ */
 export const cleanSvgString = (svgString) => {
     if (svgString.startsWith('<?xml')) {
         const endOfXml = svgString.indexOf('?>');
@@ -43,9 +64,20 @@ export const cleanSvgString = (svgString) => {
     return svgString;
 };
 
-const SVG_MIME_TYPE = 'image/svg+xml';
-
+/**
+ * Fetches and processes image data, handling both SVG and regular images.
+ * @async
+ * @param {Object} mediaData - WordPress media object
+ * @param {string} mediaData.mime - Media MIME type
+ * @param {string} mediaData.mime_type - Alternative MIME type property
+ * @param {string} mediaData.url - Media URL
+ * @param {number} mediaData.width - Image width
+ * @param {number} mediaData.height - Image height
+ * @returns {Promise<{isSvg: boolean, imageUrl: string|null, svgCode: string|null, width: number, height: number}>}
+ */
 export const getImage = async (mediaData) => {
+    const SVG_MIME_TYPE = 'image/svg+xml';
+
     const isSvg = mediaData?.mime === SVG_MIME_TYPE || mediaData?.mime_type === SVG_MIME_TYPE;
     const imagePayload = {
         isSvg,
@@ -64,6 +96,11 @@ export const getImage = async (mediaData) => {
     return imagePayload;
 };
 
+/**
+ * Formats a phone number string into XXX-XXX-XXXX format.
+ * @param {string} phone - Phone number starting with '+1' followed by 10 digits
+ * @returns {string} Formatted phone number or empty string if invalid
+ */
 export const getPhoneNumber = (phone) => {
     if (!phone) return '';
 
@@ -79,6 +116,16 @@ export const getPhoneNumber = (phone) => {
     return formatted;
 };
 
+/**
+ * Generates a formatted address string from location components.
+ * @param {Object} location - Location object
+ * @param {string} [location.street_number] - Street number
+ * @param {string} [location.street_name] - Street name
+ * @param {string} [location.city] - City
+ * @param {string} [location.state_short] - State abbreviation
+ * @param {string} [location.post_code] - Postal code
+ * @returns {string} Formatted address with HTML line breaks
+ */
 export const getLocationAddress = (location) => {
     const {
         street_number = '',
@@ -110,6 +157,11 @@ export const getLocationAddress = (location) => {
     return addressParts.join('');
 };
 
+/**
+ * Decodes HTML entities to their corresponding characters.
+ * @param {string} text - Text containing HTML entities
+ * @returns {string} Decoded text
+ */
 export const decodeHtmlEntities = (text) => {
     const tempElement = document.createElement('div');
     tempElement.innerHTML = text;
@@ -144,3 +196,42 @@ export const getSpacingClasses = (
         [`${mobilePrefix}pb-${spacing?.mobile?.padding?.bottom}`]: spacing?.mobile?.padding?.bottom !== -1,
     });
 };
+
+/**
+ * Retrieves WordPress filters by namespace.
+ * @param {string} namespace - Filter namespace to search for
+ * @returns {Array<{filterName: string, namespace: string}>} Array of matching filters
+ */
+const getFiltersByNamespace = (namespace) => {
+    const list = [];
+
+    Object.entries(filters).forEach(([filterName, filterData]) => {
+        const handlers = filterData.handlers || [];
+
+        handlers.forEach((handler) => {
+            if (handler.namespace.startsWith(namespace)) {
+                list.push({ filterName, namespace: handler.namespace });
+            }
+        });
+    });
+
+    return list;
+};
+
+/**
+ * Unregisters a block type for a specific post type when editor loads.
+ * @param {string} blockName - Name of the block to unregister
+ * @param {string} postType - Post type to check against
+ */
+const unsetBlockForPostType = (blockName, postType) => {
+    const unsubscribe = subscribe(
+        () => {
+            const currentPostType = select('core/editor').getCurrentPostType();
+            if (currentPostType === postType && getBlockType(blockName)) {
+                unregisterBlockType(blockName);
+                unsubscribe();
+            }
+        },
+        'core/editor'
+    );
+}

package/src/utils/index.js

@@ -1,5 +1,5 @@
 export * from './rootBlock/index.js';
-export * from './waitForContainer/index.js';
+export * from './rootContainer/index.js';
 
 export * from './attributes.js';
 export * from './constants.js';

package/src/utils/rootBlock/{setRootBlockAppender.js → appender.js}

@@ -1,25 +1,17 @@
 import { createBlock } from '@wordpress/blocks';
 import { dispatch } from '@wordpress/data';
 
-import { waitForContainer } from '../waitForContainer/index.js';
+import { getRootContainer } from '../rootContainer/index.js';
 
-const ROOT_CONTAINER_SELECTOR = '.is-root-container';
-const ROOT_BLOCK_APPENDER_SELECTOR = '.is-root-container .root-block-appender';
+const ROOT_BLOCK_APPENDER_SELECTOR = '.root-block-appender';
 
 /**
  * Initializes the custom button for the root appender.
+ * @param {Element} rootContainer - The root container of the editor.
  * @param {string} blockName - The name of the block to be created when the appender is clicked.
  * @param {string} tooltipText - The tooltip text displayed on the appender.
  */
-const initialize = (blockName, tooltipText) => {
-    const rootContainer = document.querySelector(ROOT_CONTAINER_SELECTOR);
-
-    if (!rootContainer) {
-        console.error('Root container not found');
-
-        return;
-    }
-
+const initialize = (rootContainer, blockName, tooltipText) => {
     const button = document.createElement('button');
 
     button.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" focusable="false"><path d="M11 12.5V17.5H12.5V12.5H17.5V11H12.5V6H11V11H6V12.5H11Z"></path></svg>';
@@ -32,6 +24,8 @@ const initialize = (blockName, tooltipText) => {
     });
 
     rootContainer.prepend(button);
+
+    return !!rootContainer.querySelector(ROOT_BLOCK_APPENDER_SELECTOR);
 };
 
 /**
@@ -42,13 +36,27 @@ const initialize = (blockName, tooltipText) => {
  * @param {string} [tooltipText='Add Row'] - The tooltip text displayed on the appender.
  */
 export const setRootBlockAppender = (blockName, tooltipText = 'Add Row') => {
-    waitForContainer(() => initialize(blockName, tooltipText), ROOT_CONTAINER_SELECTOR);
+    const rootContainer = getRootContainer();
+
+    if (rootContainer) {
+        initialize(rootContainer, blockName, tooltipText);
+    } else {
+        console.error('Root container is not found.')
+    }
 };
 
 export const unsetRootBlockAppender = () => {
-    const appender = document.querySelector(ROOT_BLOCK_APPENDER_SELECTOR);
-
-    if (appender) {
-        appender.remove();
+    const rootContainer = getRootContainer();
+
+    if (rootContainer) {
+        const appender = rootContainer.querySelector(ROOT_BLOCK_APPENDER_SELECTOR);
+
+        if (appender) {
+            appender.remove();
+        } else {
+            console.error('Root block appender is not found.');
+        }
+    } else {
+        console.error('Root container is not found.')
     }
-}
+};

package/src/utils/rootBlock/index.js

@@ -1,4 +1,6 @@
-export * from './setRootBlock.js';
-export * from './setRootBlockAppender.js';
+export * from './setRootBlockForPostTypes.js'
+export * from './setRootBlockFilter.js'
+export * from './unsetRootBlockFilter.js';
+export * from './rootBlockVisibilityFilter.js';
+export * from './appender.js';
 export * from './hideRootBlockForInlineInserter.js';
-export * from './hideRootBlockForOtherBlocks.js';

package/src/utils/rootBlock/rootBlockVisibilityFilter.js

@@ -0,0 +1,35 @@
+import { addFilter, removeFilter } from '@wordpress/hooks';
+import { getBlockTypes } from '@wordpress/blocks';
+
+export const rootBlockVisibilityFilter = {
+    add({ rootBlockName }) {
+        addFilter(
+            'blocks.registerBlockType',
+            'ssm/root-block-visibility',
+            (blockSettings, blockName) => {
+                const isRootBlock = blockName === rootBlockName;
+                const hasOwnAllowedBlocks = !!blockSettings?.allowedBlocks;
+                const hasParent = !!blockSettings?.parent;
+
+                if (isRootBlock || hasParent || hasOwnAllowedBlocks) {
+                    return blockSettings;
+                }
+
+                // get all blockTypes
+                blockSettings.allowedBlocks = getBlockTypes()
+                    ?.filter((allowedBlock) => {
+                        const isRootBlock = allowedBlock.name === rootBlockName;
+                        const hasParent = !!allowedBlock?.parent;
+
+                        return !isRootBlock && !hasParent;
+                    })
+                    ?.map(allowedBlock => allowedBlock.name);
+
+                return blockSettings;
+            },
+        );
+    },
+    remove() {
+        removeFilter('blocks.registerBlockType', 'ssm/root-block-visibility');
+    },
+};

package/src/utils/rootBlock/setRootBlockFilter.js

@@ -0,0 +1,29 @@
+import { addFilter, removeFilter } from '@wordpress/hooks';
+
+/**
+ * Adds a filter to set the specified block as the root block by modifying block settings during registration.
+ * Blocks other than the root block will have their 'ancestor' property set to the root block name,
+ * making them only insertable within the root block.
+ */
+export const setRootBlockFilter = {
+    add(rootBlockName) {
+        addFilter(
+            'blocks.registerBlockType',
+            'ssm/set-root-block',
+            (settings, name) => {
+                const isRootBlock = name === rootBlockName;
+                const isBaseBlock = name === 'core/block';
+                const hasAncestor = !!settings?.ancestor;
+
+                if (!isRootBlock && !isBaseBlock && !hasAncestor) {
+                    settings.ancestor = [rootBlockName];
+                }
+
+                return settings;
+            },
+        );
+    },
+    remove() {
+        removeFilter('blocks.registerBlockType', 'ssm/set-root-block');
+    },
+};

package/src/utils/rootBlock/setRootBlockForPostTypes.js

@@ -0,0 +1,73 @@
+import { dispatch, select, subscribe } from '@wordpress/data';
+import { setRootBlockFilter } from './setRootBlockFilter.js';
+import { unsetRootBlockFilter } from './unsetRootBlockFilter.js';
+import { rootBlockVisibilityFilter } from './rootBlockVisibilityFilter.js';
+import { waitForRootContainer } from '../rootContainer/index.js';
+import { setRootBlockAppender, unsetRootBlockAppender } from './appender.js';
+
+/**
+ * Configures a root block for specific post types
+ *
+ * @param {string} rootBlockName - The name of the root block to set.
+ * @param {Array<string>} [postTypes=['page', 'post']] - The post types for which the root block should be enabled.
+ * @param {Function} [callback] - Optional callback to execute when the root block state changes.
+ * @param {Array<Object>} [filters=[rootBlockVisibilityFilter]] - Filters to apply or remove when enabling/disabling the root block.
+ * @param {boolean} [initAppender=true] - Whether to initialize the root block appender.
+ * @param {string} [appenderTooltipText='Add Row'] - Tooltip text for the root block appender.
+ */
+export const setRootBlockForPostTypes = (
+    rootBlockName,
+    postTypes = ['page', 'post'],
+    callback,
+    filters = [ rootBlockVisibilityFilter ],
+    initAppender = true,
+    appenderTooltipText = 'Add Row',
+) => {
+    let isRootBlockEnabled = false;
+
+    waitForRootContainer().then(() => {
+        console.log('Root Container found.');
+
+        subscribe(() => {
+            const currentPostType = select('core/editor').getCurrentPostType();
+
+            if (postTypes.includes(currentPostType) && !isRootBlockEnabled) {
+                isRootBlockEnabled = true;
+
+                setRootBlockFilter.add(rootBlockName);
+                unsetRootBlockFilter.remove();
+
+                if (filters?.length > 0) {
+                    filters.forEach((filter) => filter.add({ rootBlockName, isRootBlockEnabled, currentPostType }));
+                    dispatch('core/blocks').reapplyBlockTypeFilters();
+                }
+
+                if (callback) {
+                    callback({ isRootBlockEnabled, currentPostType });
+                }
+
+                if (initAppender) {
+                    setRootBlockAppender(rootBlockName, appenderTooltipText);
+                }
+            } else if (!postTypes.includes(currentPostType) && isRootBlockEnabled) {
+                isRootBlockEnabled = false;
+
+                setRootBlockFilter.remove()
+                unsetRootBlockFilter.add(rootBlockName);
+
+                if (filters?.length > 0) {
+                    filters.forEach((filter) => filter.remove({ rootBlockName, isRootBlockEnabled, currentPostType }));
+                    dispatch('core/blocks').reapplyBlockTypeFilters();
+                }
+
+                if (callback) {
+                    callback({ isRootBlockEnabled, currentPostType });
+                }
+
+                if (initAppender) {
+                    unsetRootBlockAppender();
+                }
+            }
+        }, 'core/block-editor');
+    })
+};

package/src/utils/rootBlock/unsetRootBlockFilter.js

@@ -0,0 +1,26 @@
+import { addFilter, removeFilter } from '@wordpress/hooks';
+
+/**
+ * Adds a filter to unset the root block restrictions by removing the 'ancestor' property from block settings
+ * if it includes the specified root block name.
+ */
+export const unsetRootBlockFilter = {
+    add(rootBlockName) {
+        addFilter(
+            'blocks.registerBlockType',
+            'ssm/unset-root-block',
+            (settings) => {
+                const hasRootAncestor = settings.ancestor && settings.ancestor.includes(rootBlockName);
+
+                if (hasRootAncestor) {
+                    settings.ancestor = null;
+                }
+
+                return settings;
+            },
+        );
+    },
+    remove() {
+        removeFilter('blocks.registerBlockType', 'ssm/unset-root-block');
+    },
+};

package/src/utils/rootContainer/README.md

@@ -0,0 +1,72 @@
+## Overview
+
+The `waitForRootContainer` function is a utility that periodically checks for the presence of the Gutenberg editor's root container, identified by the class `.is-root-container`. Once the container is found, it resolves a promise, allowing for additional initialization logic.
+
+## Function Signature
+
+```javascript
+/**
+ * Periodically checks for the presence of the Gutenberg editor's root container and resolves when found.
+ *
+ * @param {number} [maxAttempts=10] - The maximum number of attempts to check for the root container.
+ * @param {number} [interval=500] - The interval time (in milliseconds) between attempts.
+ * @returns {Promise<Element>} - Resolves with the root container element if found, or rejects if not found after max attempts.
+ */
+export const waitForRootContainer = (maxAttempts = 10, interval = 500);
+```
+
+### Parameters
+- **maxAttempts** (`number`, optional): The maximum number of attempts to check for the root container. Default is `10`.
+- **interval** (`number`, optional): The interval time (in milliseconds) between each attempt. Default is `500`.
+
+### Returns
+- **Promise<Element>**: Resolves with the root container element when found. Rejects with an error if the container is not found after the maximum attempts.
+
+---
+
+## Usage Example
+To use the `waitForRootContainer` function, import it into your script and handle the promise:
+
+```javascript
+import { waitForRootContainer } from '@secretstache/wordpress-gutenberg';
+
+waitForRootContainer(10, 500)
+    .then((rootContainer) => {
+        console.log('Gutenberg root container found:', rootContainer);
+        // Your initialization logic here
+    })
+    .catch((error) => {
+        console.error('Failed to find Gutenberg root container:', error);
+    });
+```
+
+### Example Output
+In this example:
+- The function checks for the Gutenberg root container (identified by `.is-root-container`) up to 10 times, waiting 500ms between each check.
+- If the container is found, it resolves with the container element.
+- If the container is not found after 10 attempts, it rejects with an error.
+
+---
+
+## getRootContainer
+
+The `getRootContainer` function retrieves the Gutenberg editor's root container element from the DOM.
+
+### Usage Example
+
+```javascript
+import { getRootContainer } from '@secretstache/wordpress-gutenberg';
+
+const rootContainer = getRootContainer();
+if (rootContainer) {
+    console.log('Gutenberg root container found:', rootContainer);
+} else {
+    console.log('Gutenberg root container not found');
+}
+```
+
+---
+
+### Notes
+- The `getRootContainer` function searches both the main DOM and an iframe (if applicable) for the Gutenberg root container with the class `.is-root-container`.
+- `waitForRootContainer` is built on top of `getRootContainer` and provides retry logic for situations where the root container is not immediately available.

package/src/utils/rootContainer/index.js

@@ -0,0 +1,42 @@
+const ROOT_CONTAINER_SELECTOR = '.is-root-container';
+
+/**
+ * Retrieves the Gutenberg editor's root container element from the DOM or an iframe.
+ *
+ * @returns {Element|null} - Returns the root container element if found, or null if not found.
+ */
+export const getRootContainer = () => {
+    const rootContainer = document.querySelector(ROOT_CONTAINER_SELECTOR);
+
+    if (rootContainer) {
+        return rootContainer;
+    }
+
+    const iframe = document.querySelector('.block-editor iframe');
+    const iframeDocument = iframe?.contentDocument || iframe?.contentWindow?.document;
+
+    return iframeDocument?.querySelector(ROOT_CONTAINER_SELECTOR) || null;
+};
+
+export const waitForRootContainer = (maxAttempts = 10, interval = 500) => {
+    return new Promise((resolve, reject) => {
+        let attempts = 0;
+
+        const checkRootContainer = () => {
+            const rootContainer = getRootContainer();
+
+            if (rootContainer) {
+                return resolve(rootContainer);
+            } else {
+                if (attempts <= maxAttempts) {
+                    attempts++;
+                    setTimeout(checkRootContainer, interval);
+                } else {
+                    reject(new Error('Root container not found after max attempts.'));
+                }
+            }
+        };
+
+        checkRootContainer();
+    });
+};