@eightshift/frontend-libs-tailwind 1.0.0

package/scripts/components/settings/settings.js

@@ -0,0 +1,48 @@
+// Based on https://developer.wordpress.org/news/2024/03/26/how-to-use-wordpress-react-components-for-plugin-pages/
+
+import { Toaster } from 'sonner';
+import { __ } from '@wordpress/i18n';
+import { Button, HStack } from '@eightshift/ui-components';
+import { icons } from '@eightshift/ui-components/icons';
+import { createContext } from '@wordpress/element';
+import { clsx } from '@eightshift/ui-components/utilities';
+import { useThemeOptions } from './use-theme-options';
+
+export const EsThemeOptionsContext = createContext(null);
+
+export const ThemeOptionsPage = ({
+	title = __('Theme options', '%g_textdomain%'),
+	children,
+	settingName = 'eightshift-theme-options',
+}) => {
+	const themeOptions = useThemeOptions(settingName);
+	const { isLoading, saveSettings } = themeOptions;
+
+	return (
+		<EsThemeOptionsContext.Provider value={themeOptions}>
+			<Toaster richColors />
+			<div
+				className={clsx(
+					'es-uic-space-y-4',
+					isLoading && 'es-uic-pointer-events-none es-uic-opacity-60'
+				)}
+			>
+				<HStack className='es-uic-justify-between'>
+					<h1>{title}</h1>
+
+					<Button
+						onPress={() => saveSettings()}
+						disabled={isLoading}
+						icon={isLoading ? icons.moreH : icons.save}
+					>
+						{isLoading
+							? __('Saving...', '%g_textdomain%')
+							: __('Save', '%g_textdomain%')}
+					</Button>
+				</HStack>
+
+				{children}
+			</div>
+		</EsThemeOptionsContext.Provider>
+	);
+};

package/scripts/components/settings/use-theme-options.js

@@ -0,0 +1,52 @@
+import { __ } from '@wordpress/i18n';
+import { useState, useEffect } from '@wordpress/element';
+import { toast } from 'sonner';
+import apiFetch from '@wordpress/api-fetch';
+
+export const useThemeOptions = (settingName) => {
+	const [settings, setSettings] = useState();
+	const [isLoading, setIsLoading] = useState(false);
+
+	useEffect(() => {
+		apiFetch({ path: '/wp/v2/settings' }).then((settings) => {
+			setSettings(settings?.[settingName]);
+		});
+	}, []);
+
+	const saveSettings = async () => {
+		setIsLoading(true);
+
+		try {
+			await apiFetch({
+				path: '/wp/v2/settings',
+				method: 'POST',
+				data: {
+					[settingName]: settings,
+				},
+			});
+
+			toast.success(__('Saved successfully', '%g_textdomain%'));
+		} catch (error) {
+			toast.error(__('Something went wrong while saving', '%g_textdomain%'), {
+				description: error.message,
+			});
+		} finally {
+			setIsLoading(false);
+		}
+	};
+
+	const updateSettings = (modified) => {
+		setSettings((prev) => ({
+			...prev,
+			...modified,
+		}));
+	};
+
+	return {
+		isLoading,
+		settings,
+		saveSettings,
+		setSettings,
+		updateSettings,
+	};
+};

package/scripts/editor/attributes.js

@@ -0,0 +1,304 @@
+import { camelCase, isEmpty, lowerFirst, upperFirst } from '@eightshift/ui-components/utilities';
+
+/**
+ * Sets attributes on all `innerBlocks`. This value will be stored in the Block editor store and set to a block.
+ *
+ * @param {function} select State function.
+ * @param {string} clientId Unique block ID from block editor.
+ * @param {object} attributesObject Object of attributes to apply.
+ * @param {array} exclude Array of block names to exclude.
+ *
+ * @access public
+ *
+ * @returns {void}
+ *
+ * Usage:
+ * ```js
+ * import { useSelect } from '@wordpress/data';
+ *
+ * useSelect((select) => {
+ *   overrideInnerBlockAttributes(
+ *     select,
+ *     props.clientId,
+ *     {
+ *       wrapperUse: false,
+ *       wrapperNoControls: true,
+ *     }
+ *   );
+ * });
+ * ```
+ */
+export const overrideInnerBlockAttributes = (select, clientId, attributesObject = {}, exclude = []) => {
+	const { getBlock } = select('core/block-editor');
+
+	const block = getBlock(clientId);
+
+	block.innerBlocks.map((item) => {
+		const {
+			attributes,
+			name,
+		} = item;
+
+		if (!exclude.includes(name)) {
+			for (const attribute in attributesObject) {
+				if (Object.prototype.hasOwnProperty.call(attributesObject, attribute)) {
+					if (attribute !== attributes[attribute]) {
+						attributes[attribute] = attributesObject[attribute];
+					}
+				}
+			}
+		}
+
+		return item;
+	});
+};
+
+/**
+ * Check if attribute exist in attributes list and add default value if not.
+ * This is used because Block editor will not output attributes that don't have default value.
+ *
+ * @param {string} key                       - Key to check.
+ * @param {array} attributes                 - Array of attributes.
+ * @param {object} manifest                  - Components/blocks manifest.json
+ * @param {boolean} [undefinedAllowed=false] - Allowed detection of undefined values.
+ *
+ * @access public
+ *
+ * @return {mixed} Based on the attribute type.
+ *                 Boolean - false
+ *                 String - ''
+ *                 Object - {}
+ *                 Array - []
+ *
+ * Manifest:
+ * ```js
+ * {
+ *  "attributes": {
+ *    "buttonUse": {
+ *       "type": "boolean"
+ *     },
+ *   },
+*    "buttonContent": {
+ *       "type": "string"
+ *     },
+ *   }
+ * }
+ * ```
+ *
+ * Usage:
+ * ```js
+ * checkAttr('buttonUse', attributes, manifest);
+ * checkAttr('buttonContent', attributes, manifest);
+ * ```
+ *
+ * Output:
+ * ```js
+ * false
+ * ''
+ * ```
+ */
+export const checkAttr = (key, attributes, manifest, undefinedAllowed = false) => {
+	// Get the correct key for the check in the attributes object.
+	const newKey = getAttrKey(key, attributes, manifest);
+
+	// If key exists in the attributes object, just return that key value.
+	if (Object.prototype.hasOwnProperty.call(attributes, newKey)) {
+		return attributes[newKey];
+	}
+
+	// Check current component attributes.
+	const manifestKey = manifest.attributes[key];
+
+	let tipOutput = '';
+
+	if ('components' in manifest) {
+		tipOutput = ' If you are using additional components, check if you used the correct block/component prefix in your attribute name.';
+	}
+
+	// Bailout if key is missing.
+	if (typeof manifestKey === 'undefined') {
+		if ('blockName' in manifest) {
+			throw Error(`${key} key does not exist in the ${manifest.blockName} block manifest. Please check your implementation.${tipOutput}`);
+		} else {
+			throw Error(`${key} key does not exist in the ${manifest.componentName} component manifest. Please check your implementation.${tipOutput}`);
+		}
+	}
+
+	// If undefinedAllowed is true and attribute is missing default just return undefined to be able to unset attribute in block editor.
+	if (!Object.prototype.hasOwnProperty.call(manifestKey, 'default') && undefinedAllowed) {
+		return undefined;
+	}
+
+	// Check type.
+	const defaultType = manifestKey.type;
+
+	let defaultValue;
+
+	// Output "default values" if none are defined.
+	switch (defaultType) {
+		case 'boolean':
+			defaultValue = Object.prototype.hasOwnProperty.call(manifestKey, 'default') ? manifestKey.default : false;
+			break;
+		case 'array':
+			defaultValue = Object.prototype.hasOwnProperty.call(manifestKey, 'default') ? manifestKey.default : [];
+			break;
+		case 'object':
+			defaultValue = Object.prototype.hasOwnProperty.call(manifestKey, 'default') ? manifestKey.default : {};
+			break;
+		default:
+			defaultValue = Object.prototype.hasOwnProperty.call(manifestKey, 'default') ? manifestKey.default : '';
+			break;
+	}
+
+	return defaultValue;
+};
+
+/**
+ * Check if attributes key has prefix and outputs the correct attribute name.
+ *
+ * @param {string} key       - Key to check.
+ * @param {array} attributes - Array of attributes.
+ * @param {object} manifest  - Components/blocks manifest.json
+ *
+ * @access public
+ *
+ * @return string
+ */
+export const getAttrKey = (key, attributes, manifest) => {
+	// Just skip if attribute is wrapper.
+	if (key.includes('wrapper')) {
+		return key;
+	}
+
+	// Skip if using this helper in block.
+	if (typeof manifest?.blockName !== 'undefined') {
+		return key;
+	}
+
+	// If missing prefix or prefix is empty return key.
+	if (typeof attributes?.prefix === 'undefined' || attributes?.prefix === '') {
+		return key;
+	}
+
+	// No need to test if this is block or component because on top level block there is no prefix.
+	// If there is a prefix, remove the attribute component name prefix and replace it with the new prefix.
+	return key.replace(camelCase(manifest.componentName), attributes.prefix);
+};
+
+/**
+ * Output only attributes that are used in the component and remove everything else.
+ *
+ * @param {string} newName     - *New* key to use to rename attributes.
+ * @param {object} attributes  - Attributes from the block/component.
+ * @param {object} [manual={}] - Object of attributes to change key and merge to the original output.
+ *
+ * @access public
+ *
+ * @returns {object}
+ *
+ * Manifest:
+ * ```js
+ * const attributes = {
+ *   buttonColor: 'red',
+ *   buttonSize: 'big',
+ *   buttonIcon: 'blue',
+ *   blockName: 'button',
+ *   wrapperSize: 'big',
+ *   wrapperType: 'normal',
+ * };
+ * ```
+ *
+ * Usage:
+ * ```js
+ * {...props('button', attributes)}
+ * ```
+ *
+ * Output:
+ * ```js
+ * {
+ *   buttonColor: 'red',
+ *   buttonSize: 'big',
+ *   buttonIcon: 'blue',
+ *   blockName: 'button',
+ * };
+ * ```
+ *
+ * Additional keys that are passed are defined in the includes array.
+ */
+export const props = (newName, attributes, manual = {}) => {
+
+	const output = {};
+
+	// Check which attributes we need to include.
+	const includes = [
+		'blockName',
+		'blockClientId',
+		'blockTopLevelId',
+		'blockFullName',
+		'blockClass',
+		'blockJsClass',
+		'componentJsClass',
+		'selectorClass',
+		'additionalClass',
+		'setAttributes',
+		'uniqueWrapperId',
+		'options',
+		'clientId',
+	];
+
+	// Check if in test mode and use different setting.
+	const blockName = process.env.NODE_ENV === 'test' ? attributes.blockName.default : attributes.blockName;
+
+	// Populate prefix key for recursive checks of attribute names.
+	const prefix = (typeof attributes.prefix === 'undefined') ? camelCase(blockName) : attributes['prefix'];
+
+	// Set component prefix.
+	if (prefix === '') {
+		output['prefix'] = camelCase(newName);
+	} else {
+		output['prefix'] = `${prefix}${upperFirst(camelCase(newName))}`;
+	}
+
+	// Iterate over attributes.
+	for (const [key, value] of Object.entries(attributes)) {
+
+		// Includes attributes from iteration.
+		if (includes.includes(key)) {
+			Object.assign(output, { [key]: value });
+			continue;
+		}
+
+		// If attribute starts with the prefix key leave it in the object if not remove it.
+		if (key.startsWith(output['prefix'])) {
+			Object.assign(output, { [key]: value });
+		}
+	}
+
+	// Check if you have manual object and prepare the attribute keys and merge them with the original attributes for output.
+	if (!isEmpty(manual)) {
+		// Iterate manual attributes.
+		for (let [key, value] of Object.entries(manual)) {
+
+			// Includes attributes from iteration.
+			if (includes.includes(key)) {
+				Object.assign(output, { [key]: value });
+				continue;
+			}
+
+			// Remove the current component name from the attribute name.
+			const newKey = key.replace(`${lowerFirst(camelCase(newName))}`, '');
+
+			// Remove the old key.
+			delete manual[key];
+
+			// // Add new key to the output with prepared attribute name.
+			Object.assign(manual, { [`${output['prefix']}${newKey}`]: value });
+		}
+
+		// Merge manual and output objects to one.
+		Object.assign(output, manual);
+	}
+
+	// Return the original attribute for optimization purposes.
+	return output;
+};

package/scripts/editor/colors.js

@@ -0,0 +1,64 @@
+import { useSelect } from '@wordpress/data';
+import { STORE_NAME } from './store';
+import { upperFirst } from '@eightshift/ui-components/utilities';
+
+/**
+ * Returns colors from the global stores from the theme.
+ *
+ * @access public
+ *
+ * @returns {object}
+ *
+ * Usage:
+ * ```js
+ * getPaletteColors()
+ * ```
+ */
+export const getPaletteColors = () => useSelect((select) => {
+	const colors = select(STORE_NAME).getSettings().globalVariables.colors;
+
+	return colors.reduce(
+		(obj, item) => ({
+			...obj,
+			[item.slug]: item,
+		}),
+		{}
+	);
+});
+
+export const getColorData = (themeColors) => Object.entries(themeColors ?? {})?.reduce((curr, [name, value]) => {
+	if (name === 'current') {
+		return curr;
+	}
+
+	if (name === 'transparent') {
+		return [
+			...curr,
+			{
+				name: 'Transparent',
+				slug: 'transparent',
+				color: '#00000000',
+			}
+		];
+	}
+
+	if (typeof value === 'string') {
+		return [
+			...curr,
+			{
+				name: upperFirst(name),
+				slug: name,
+				color: value,
+			}
+		];
+	}
+
+	return [
+		...curr,
+		...Object.entries(value).map(([shade, color]) => ({
+			name: `${upperFirst(name)} ${shade}`,
+			slug: `${name}-${shade}`,
+			color,
+		})),
+	];
+}, []) ?? [];

package/scripts/editor/editor.js

@@ -0,0 +1,139 @@
+import React from 'react';
+import { dispatch } from '@wordpress/data';
+import { InspectorControls, BlockControls } from '@wordpress/block-editor';
+import { ContainerPanel } from '@eightshift/ui-components';
+import { upperFirst } from '@eightshift/ui-components/utilities';
+
+/**
+ * Given a block's client ID and an attribute key, locks post saving in Gutenberg.
+ * A lock is created under the name undefined-lock-[blockClientId]-[attributeKey],
+ * meaning that a lock can be created for each attribute key of each block.
+ * Multiple locks can be present and all of them have to be removed before saving is unlocked.
+ *
+ * @param {string} blockClientId A block's client ID
+ * @param {string} attributeKey The attribute key
+ *
+ * @access public
+ *
+ * @returns {void}
+ *
+ * Usage:
+ * ```js
+ * lockPostEditing(clientId, getAttrKey('headingContent', attributes, manifest), value);
+ * ```
+ */
+export const lockPostEditing = (blockClientId, attributeKey) => {
+	dispatch('core/editor').lockPostSaving(`undefined-lock-${blockClientId}-${attributeKey}`);
+};
+
+/**
+ * Given a block's client ID and an attribute key, unlocks post saving in Gutenberg.
+ * A lock is created under the name undefined-lock-[blockClientId]-[attributeKey],
+ * meaning that a lock can be created for each attribute key of each block.
+ * Multiple locks can be present and all of them have to be removed before saving is unlocked.
+ *
+ * @param {string} blockClientId A block's client ID
+ * @param {string} attributeKey The attribute key
+ *
+ * @access public
+ *
+ * @returns {void}
+ *
+ * Usage:
+ * ```js
+ * unlockPostEditing(clientId, getAttrKey('headingContent', attributes, manifest), value);
+ * ```
+ */
+export const unlockPostEditing = (blockClientId, attributeKey) => {
+	dispatch('core/editor').unlockPostSaving(`undefined-lock-${blockClientId}-${attributeKey}`);
+};
+
+/**
+ * Given a block's client ID, attribute key and new value, creates a lock, locks post saving in Gutenberg
+ * if the value is undefined, null or an empty string and unlocks that attribute's lock otherwise.
+ *
+ * A lock is created under the name undefined-lock-[blockClientId]-[attributeKey],
+ * meaning that a lock can be created for each attribute key of each block.
+ * Multiple locks can be present and all of them have to be removed before saving is unlocked.
+ *
+ * @param {string} blockClientId A block's client ID
+ * @param {string} attributeKey The attribute key
+ *
+ * @access public
+ *
+ * @returns {void}
+ *
+ * Usage:
+ * ```js
+ * onChange={(value) => {
+ *  setAttributes({ [getAttrKey('headingContent', attributes, manifest)]: value });
+ *  lockIfUndefined(clientId, getAttrKey('headingContent', attributes, manifest), value);
+ * }}
+ * ```
+ */
+export const lockIfUndefined = (blockClientId, attributeKey, value) => {
+	if (typeof value === 'undefined' || value === null || value === '') {
+		lockPostEditing(blockClientId, attributeKey);
+		return;
+	}
+	unlockPostEditing(blockClientId, attributeKey);
+};
+
+/**
+ * Initialize the block context with all necessary data
+ *
+ * @component
+ * @param {Object} props - Component props.
+ * @param {JSX.Element?} [props.options] - Options component
+ * @param {JSX.Element?} [props.toolbar] - Toolbar component
+ * @param {JSX.Element?} [props.editor] - Editor component
+ * @param {boolean} [props.noOptionsContainer] - If `true`, the options component will not be wrapped in a container.
+ * @param {string} props.title - Block name. Will fall back to a name generated from the `blockName` attribute.
+ *
+ * @returns {JSX.Element} The GutenbergBlock component.
+ *
+ * @access public
+ * @since 1.0.0
+ *
+ * @example
+ * <GutenbergBlock
+ * 	{...props}
+ * 	options={OptionsComponent}
+ * 	editor={EditorComponent}
+ * />
+ *
+ */
+export const GutenbergBlock = (props) => {
+	const {
+		options: OptionsComponent,
+		toolbar: ToolbarComponent,
+		editor: EditorComponent,
+		noOptionsContainer = false,
+		title,
+	} = props;
+
+	return (
+		<>
+			{OptionsComponent &&
+				<InspectorControls>
+					{!noOptionsContainer &&
+						<ContainerPanel title={title ?? upperFirst(props?.attributes?.blockName)}>
+							<OptionsComponent {...props} />
+						</ContainerPanel>
+					}
+					{noOptionsContainer && <OptionsComponent {...props} />}
+				</InspectorControls>
+			}
+
+			{ToolbarComponent &&
+				<BlockControls>
+					<ToolbarComponent {...props} />
+				</BlockControls>
+			}
+
+			{EditorComponent &&
+				<EditorComponent {...props} />
+			}
+		</>
+	);
+};

package/scripts/editor/fetch.js

@@ -0,0 +1,102 @@
+import { unescapeHTML } from '@eightshift/ui-components/utilities';
+
+/**
+ * Returns a function that fetches data from WordPress REST API.
+ *
+ * @param {string} endpoint - Endpoint to fetch from.
+ * @param {Object} options - Additional options.
+ * @param {Function} [options.processId] - Function to process the ID. `(itemData: Object) => id: string | Number`
+ * @param {Function} [options.processLabel] - Function to process the label. `(itemData: Object) => label: string`
+ * @param {Function} [options.processMetadata] - Function to process the metadata. `(itemData: Object) => metadata: Object`
+ * @param {number} [options.perPage=30] - Number of items to fetch per page.
+ * @param {string} [options.urlBase='<origin>/wp-json'] - Base URL for the API.
+ * @param {string} [options.routePrefix='wp/v2'] - Route prefix for the API.
+ * @param {string} [options.fields='id,title'] - A comma-separated list of field names to fetch from the API. Good to include as it makes the query faster and the output terser.
+ * @param {SearchColumnsConfig} [options.searchColumns] - Allows narrowing the search scope.
+ * @param {boolean} [options.noUnescapeTitle] - If `true`, the post title will not unescape HTML entities.
+ *
+ * @returns {Function} The `(searchText, [abortSignal]) => Promise` function.
+ *
+ * @typedef {'post_title' | 'post_excerpt' | 'post_content'} SearchColumnsConfig
+ *
+ * @example
+ * const fetchFn = getFetchWpApi('pages');
+ * const data = await fetchFn('search text');
+ * const json = await data.json();
+ *
+ * console.log(json);
+ *
+ * @example
+ * <LinkInput
+ *  value={buttonUrl}
+ *  onChange={({url}) => setAttributes({ [getAttrKey('buttonUrl', attributes, manifest)]: url })}
+ *  fetchSuggestions={getFetchWpApi('search')}
+ * />
+ *
+ */
+export function fetchFromWpRest(endpoint, options = {}) {
+	const {
+		processId = ({ id }) => id,
+		processLabel = ({ title }) => unescapeHTML(title),
+		processMetadata = () => null,
+		perPage = 30,
+		urlBase = `${window.location.origin}/wp-json`,
+		routePrefix = 'wp/v2',
+		fields = 'id,title',
+		searchColumns,
+		noUnescapeTitle = false,
+		...params
+	} = options;
+
+	return async (searchText = '', abortSignal) => {
+		const url = new URL(`${urlBase}/${routePrefix}/${endpoint}/`);
+
+		url.searchParams.append('per_page', perPage);
+
+		if (fields?.length > 0) {
+			url.searchParams.append('_fields', fields);
+		}
+
+		if (searchColumns?.length > 0) {
+			url.searchParams.append('search_columns', Array.isArray(searchColumns) ? searchColumns.join(',') : searchColumns);
+		}
+
+		if (Object.keys(params).length > 0) {
+			for (const [key, value] of Object.entries(params)) {
+				url.searchParams.append(key, value);
+			}
+		}
+
+		if (searchText?.length > 0) {
+			url.searchParams.append('search', searchText);
+		}
+
+		const newData = await fetch(url.toString(), {
+			signal: abortSignal,
+		});
+
+		const newDataJson = await newData.json();
+
+		return [...newDataJson].map((item) => {
+			return {
+				label: noUnescapeTitle ? unescapeHTML(processLabel(item)) : processLabel(item),
+				value: processId(item),
+				metadata: processMetadata(item),
+			};
+		});
+	};
+}
+
+export const wpSearchRoute = fetchFromWpRest('search', {
+	processId: ({ url }) => url,
+	processLabel: ({ title }) => title,
+	processMetadata: ({ type, subtype }) => ({ type, subtype }),
+	additionalParam: {
+		type: 'post',
+		_locale: 'user',
+		per_page: 5,
+	},
+	noCache: true,
+	searchColumns: 'post_title',
+	fields: 'id,title,type,subtype,url',
+});