@eightshift/frontend-libs-tailwind 1.3.3 → 1.4.0

package/schemas/component.json

@@ -101,7 +101,7 @@
 			"properties": {
 				"attributes": {
 					"type": "object",
-					"description": "Set the attribues for the block example"
+					"description": "Set the attributes for the block example"
 				},
 				"innerBlocks": {
 					"type": "array",
@@ -119,18 +119,32 @@
 		},
 		"tailwind": {
 			"type": "object",
-			"description": "Defines shared Tailwind configs for the component. 'base' sets the base classes for the main part of the component. The base is augmented by 'options' and 'combinations', if set. 'parts' can be used for static/supporting parts of the component.",
+			"description": "Defines shared Tailwind configs for the component. Allows defining flexible parts, option-based classes, and combinations to add various styles.",
 			"properties": {
 				"base": {
+					"deprecated": true,
 					"type": "object",
-					"description": "Base classes for the main part of the component.",
+					"description": "DEPRECATED - move into parts (part should be named 'base')! Base classes for the main part of the component.",
 					"properties": {
 						"twClasses": {
-							"type": ["string", "array"],
+							"type": [
+								"string",
+								"array"
+							],
 							"description": "Classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability."
 						},
 						"twClassesEditor": {
-							"type": ["string", "array"],
+							"type": [
+								"string",
+								"array"
+							],
+							"description": "Editor-specific classnames to apply. These classes are added to 'twClassesEditorOnly'/'twClasses'. An array of classnames (strings) can also be provided for improved manifest readability."
+						},
+						"twClassesEditorOnly": {
+							"type": [
+								"string",
+								"array"
+							],
 							"description": "Editor-specific classnames to apply. Overrides 'twClasses'. An array of classnames (strings) can also be provided for improved manifest readability."
 						}
 					},
@@ -138,7 +152,7 @@
 				},
 				"options": {
 					"type": "object",
-					"description": "Per-attribute classes, added to the base class. Key represents the attribute name.",
+					"description": "Per-attribute classes, added to one or more parts, or different classes per part. Key represents the attribute name.",
 					"additionalProperties": {
 						"$ref": "#/$defs/twOptionsEntry"
 					},
@@ -146,7 +160,7 @@
 				},
 				"parts": {
 					"type": "object",
-					"description": "Stand-alone parts of the component, not affected by 'options' or 'combinations'. Key represents the part name.",
+					"description": "Parts of the component. Key represents the part name.",
 					"additionalProperties": {
 						"$ref": "#/$defs/twPartEntry"
 					},
@@ -154,7 +168,7 @@
 				},
 				"combinations": {
 					"type": "array",
-					"description": "Conditionally applied classes, depending on the set attribute values. Added to the base class.",
+					"description": "Conditionally applied classes, depending on the set attribute values. Added to the chosen part, or different classes per part.",
 					"items": {
 						"type": "object",
 						"properties": {
@@ -165,13 +179,21 @@
 									"[a-zA-Z]": {
 										"anyOf": [
 											{
-												"type": ["string", "number", "boolean"],
+												"type": [
+													"string",
+													"number",
+													"boolean"
+												],
 												"minLength": 1
 											},
 											{
 												"type": "array",
 												"items": {
-													"type": ["string", "number", "boolean"],
+													"type": [
+														"string",
+														"number",
+														"boolean"
+													],
 													"minLength": 1
 												}
 											}
@@ -180,17 +202,36 @@
 								}
 							},
 							"twClasses": {
-								"type": ["string", "array"],
+								"type": [
+									"string",
+									"array"
+								],
 								"description": "Classnames to apply if all conditions match. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability."
 							},
 							"twClassesEditor": {
-								"type": ["string", "array"],
+								"type": [
+									"string",
+									"array"
+								],
+								"description": "Editor-specific classnames to apply if all conditions match. These classes are added to 'twClassesEditorOnly'/'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability."
+							},
+							"twClassesEditorOnly": {
+								"type": [
+									"string",
+									"array"
+								],
 								"description": "Editor-specific classnames to apply if all conditions match. Overrides 'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability."
+							},
+							"output": {
+								"type": "object",
+								"description": "Allows outputting different classes per part for this combination. Key is the part name, value is an object with class definitions ('twClasses'/'twClassesEditor'/'twClassesEditorOnly'). Overrides 'twClasses'/'twClassesEditor'/'twClassesEditorOnly' if set.",
+								"additionalProperties": {
+									"$ref": "#/$defs/twPartEntry"
+								}
 							}
 						},
 						"required": [
-							"attributes",
-							"twClasses"
+							"attributes"
 						]
 					},
 					"minLength": 1
@@ -208,11 +249,24 @@
 			"type": "object",
 			"properties": {
 				"twClasses": {
-					"type": ["string", "array"],
+					"type": [
+						"string",
+						"array"
+					],
 					"description": "Classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability."
 				},
 				"twClassesEditor": {
-					"type": ["string", "array"],
+					"type": [
+						"string",
+						"array"
+					],
+					"description": "Editor-specific classnames to apply. These classes are added to 'twClassesEditorOnly'/'twClasses'. An array of classnames (strings) can also be provided for improved manifest readability."
+				},
+				"twClassesEditorOnly": {
+					"type": [
+						"string",
+						"array"
+					],
 					"description": "Editor-specific classnames to apply. Overrides 'twClasses'. An array of classnames (strings) can also be provided for improved manifest readability."
 				}
 			}
@@ -224,19 +278,74 @@
 					"type": "object",
 					"description": "Classnames to apply. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
 					"additionalProperties": {
-						"type": ["string", "array"]
+						"type": [
+							"string",
+							"array"
+						]
 					}
 				},
 				"twClassesEditor": {
+					"type": "object",
+					"description": "Editor-specific classnames to apply. These classes are added to 'twClassesEditorOnly'/'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
+					"additionalProperties": {
+						"type": [
+							"string",
+							"array"
+						]
+					}
+				},
+				"twClassesEditorOnly": {
 					"type": "object",
 					"description": "Editor-specific classnames to apply. Overrides 'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
 					"additionalProperties": {
-						"type": ["string", "array"]
+						"type": [
+							"string",
+							"array"
+						]
 					}
 				},
 				"part": {
-					"type": ["string", "array"],
-					"description": "Part to assign the class output to. If not specified, the classes are added to the base class. You can also specify an array of parts to apply the classes to."
+					"type": "string",
+					"description": "Part to assign the class output to. If not specified, the classes are added to the base class. Specify multiple parts by separating their names with commas. NOTE: if classes are specified per-part, this list will be ignored!"
+				},
+				"responsive": {
+					"type": "boolean",
+					"description": "Set to 'true' if the option has the ability to have per-breakpoint values."
+				}
+			},
+			"additionalProperties": {
+				"type": "object",
+				"properties": {
+					"twClasses": {
+						"type": "object",
+						"description": "Classnames to apply. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
+						"additionalProperties": {
+							"type": [
+								"string",
+								"array"
+							]
+						}
+					},
+					"twClassesEditor": {
+						"type": "object",
+						"description": "Editor-specific classnames to apply. These classes are added to 'twClassesEditorOnly'/'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
+						"additionalProperties": {
+							"type": [
+								"string",
+								"array"
+							]
+						}
+					},
+					"twClassesEditorOnly": {
+						"type": "object",
+						"description": "Editor-specific classnames to apply. Overrides 'twClasses'. Key is the attribute value, value is the classnames to apply. An array of classnames (strings) can also be provided for improved manifest readability.",
+						"additionalProperties": {
+							"type": [
+								"string",
+								"array"
+							]
+						}
+					}
 				}
 			}
 		}

package/schemas/globalManifest.json

@@ -1,5 +1,5 @@
 {
-	"title": "JSON schema for Eightshift global manifest",
+	"title": "JSON schema for Frontend libs Tailwind global manifest",
 	"$schema": "http://json-schema.org/draft-04/schema#",
 	"type": "object",
 	"properties": {

package/scripts/editor/tailwindcss.js

@@ -12,6 +12,8 @@ import { clsx } from '@eightshift/ui-components/utilities';
  *
  * @returns {string} Output classes.
  *
+ * @deprecated Since 1.4.0. Use `tailwindClasses` instead.
+ *
  * @example
  * const classes = getTwPart('intro', manifest);
  *
@@ -46,6 +48,8 @@ export const getTwPart = (part, manifest, ...custom) => {
  *
  * @returns {string} Output classes.
  *
+ * @deprecated Since 1.4.0. Use `tailwindClasses` instead.
+ *
  * @example
  * const classes = getTwPart('intro', manifest);
  *
@@ -118,6 +122,8 @@ export const getTwDynamicPart = (part, attributes, manifest, ...custom) => {
  *
  * @returns {string} Output classes
  *
+ * @deprecated Since 1.4.0. Use `tailwindClasses` instead.
+ *
  * @example
  * const classes = getTwClasses(attributes, manifest);
  *
@@ -341,3 +347,206 @@ const combineAndRemoveDuplicates = (results) => {
 		return acc;
 	}, {});
 };
+
+const unifyClasses = (classes) => {
+	if (Array.isArray(classes)) {
+		return clsx(...classes);
+	}
+
+	return classes.trim();
+};
+
+const processOption = (partName, optionValue, defs) => {
+	let optionClasses = [];
+
+	const isResponsive = defs?.responsive === true;
+	const itemPartName = defs?.part ?? 'base';
+	const isSingleValue = 'twClasses' in defs || 'twClassesEditor' in defs || 'twClassesEditorOnly' in defs;
+
+	// Part checks.
+	if (!isSingleValue && typeof defs?.[partName] === 'undefined') {
+		return '';
+	}
+
+	if (isSingleValue && !itemPartName.includes(partName)) {
+		return '';
+	}
+
+	// Non-responsive options.
+	if (!isResponsive) {
+		const rawValueBase =
+			defs?.twClassesEditorOnly?.[optionValue] ??
+			defs?.twClasses?.[optionValue] ??
+			defs?.[partName]?.twClassesEditorOnly?.[optionValue] ??
+			defs?.[partName]?.twClasses?.[optionValue] ??
+			'';
+
+		const rawValueEditor =
+			defs?.twClassesEditor?.[optionValue] ?? defs?.[partName]?.twClassesEditor?.[optionValue] ?? '';
+
+		return clsx(unifyClasses(rawValueBase), unifyClasses(rawValueEditor));
+	}
+
+	// Responsive options.
+	const breakpoints = Object.keys(optionValue).filter((key) => key !== '_desktopFirst');
+
+	for (const breakpoint of breakpoints) {
+		const breakpointValue = optionValue?.[breakpoint];
+
+		if (typeof breakpointValue === 'undefined') {
+			continue;
+		}
+
+		const rawValueBase =
+			defs?.twClassesEditorOnly?.[breakpointValue] ??
+			defs?.twClasses?.[breakpointValue] ??
+			defs?.[partName]?.twClassesEditorOnly?.[breakpointValue] ??
+			defs?.[partName]?.twClasses?.[breakpointValue] ??
+			'';
+
+		const rawValueEditor =
+			defs?.twClassesEditor?.[breakpointValue] ?? defs?.[partName]?.twClassesEditor?.[breakpointValue] ?? '';
+
+		if (breakpoint === '_default') {
+			optionClasses = [...optionClasses, unifyClasses(rawValueBase), unifyClasses(rawValueEditor)];
+
+			continue;
+		}
+
+		const splitClassesBase = unifyClasses(rawValueBase)
+			.split(' ')
+			.filter(Boolean)
+			.map((currentClass) => `${breakpoint}:${currentClass}`);
+
+		const splitClassesEditor = unifyClasses(rawValueEditor)
+			.split(' ')
+			.filter(Boolean)
+			.map((currentClass) => `${breakpoint}:${currentClass}`);
+
+		optionClasses = [...optionClasses, unifyClasses(splitClassesBase), unifyClasses(splitClassesEditor)];
+	}
+
+	return unifyClasses(optionClasses);
+};
+
+const processCombination = (partName, combo, attributes, manifest) => {
+	let matches = true;
+
+	for (const [attributeName, allowedValue] of Object.entries(combo?.attributes ?? {})) {
+		const optionValue = checkAttr(attributeName, attributes, manifest, true);
+
+		if (Array.isArray(allowedValue) && !allowedValue.includes(optionValue)) {
+			matches = false;
+			break;
+		}
+
+		if (optionValue !== allowedValue) {
+			matches = false;
+			break;
+		}
+	}
+
+	if (!matches) {
+		return '';
+	}
+
+	const itemPartName = combo?.part ?? 'base';
+	const isSingleValue = 'twClasses' in combo || 'twClassesEditor' in combo || 'twClassesEditorOnly' in combo;
+
+	if (isSingleValue && !partName.includes(itemPartName)) {
+		return '';
+	}
+
+	const rawValueBase =
+		combo?.output?.[partName]?.twClassesEditorOnly ??
+		combo?.output?.[partName]?.twClasses ??
+		combo?.twClassesEditorOnly ??
+		combo?.twClasses ??
+		'';
+
+	const rawValueEditor = combo?.output?.[partName]?.twClassesEditor ?? combo?.twClassesEditor ?? '';
+
+	if (!Array.isArray(rawValueBase) && typeof rawValueBase !== 'string') {
+		throw new Error(
+			'Combination classes/editor-only classes were not defined correctly. Please check the combination definition in the manifest.',
+		);
+	}
+
+	if (!Array.isArray(rawValueEditor) && typeof rawValueEditor !== 'string') {
+		throw new Error(
+			'Combination editor classes were not defined correctly. Please check the combination definition in the manifest.',
+		);
+	}
+
+	return clsx(unifyClasses(rawValueBase), unifyClasses(rawValueEditor));
+};
+
+/**
+ * Get Tailwind classes from attributes and manifest.
+ *
+ * @param {string} part - Part to get classes for.
+ * @param {Object<string, mixed>} attributes - Component/block attributes.
+ * @param {Object<string, mixed>} manifest - Component/block manifest data.
+ * @param {...string?} custom - Custom classes to include in the output.
+ *
+ * @returns {string} Output classes
+ *
+ * @example
+ * const classes = tailwindClasses(attributes, manifest);
+ *
+ * @example
+ * const classes = tailwindClasses(attributes, manifest, 'p-4 bg-gray-100');
+ *
+ */
+export const tailwindClasses = (part, attributes, manifest, ...custom) => {
+	// If nothing is set, return custom classes as a fallback.
+	if (!attributes || !manifest || !manifest?.tailwind || Object.keys(manifest?.tailwind ?? {}).length === 0) {
+		return clsx(...custom);
+	}
+
+	const allParts = ['base', ...Object.keys(manifest?.tailwind?.parts ?? {})];
+
+	let partName = 'base';
+
+	if (part?.length > 0 && typeof manifest.tailwind.parts[part] !== 'undefined' && allParts.includes(part)) {
+		partName = part;
+	} else if (part !== 'base') {
+		throw new Error(`Part '${part}' is not defined in the manifest.`);
+	}
+
+	// Base classes.
+	const baseBaseClasses = manifest?.tailwind?.parts?.[partName]?.twClassesEditorOnly ??
+		manifest?.tailwind?.parts?.[partName]?.twClasses ??
+		manifest?.tailwind?.base?.twClassesEditorOnly ??
+		manifest?.tailwind?.base?.twClasses ?? [''];
+	const baseEditorClasses = manifest?.tailwind?.parts?.[partName]?.twClassesEditor ??
+		manifest?.tailwind?.base?.twClassesEditor ?? [''];
+
+	// Option classes.
+	const options = manifest?.tailwind?.options ?? {};
+
+	let optionClasses = [];
+
+	for (const [attributeName, defs] of Object.entries(options)) {
+		const optionValue = checkAttr(attributeName, attributes, manifest, true);
+
+		optionClasses = [...optionClasses, processOption(partName, optionValue, defs)];
+	}
+
+	// Combinations.
+	const combinations = manifest?.tailwind?.combinations ?? [];
+
+	let combinationClasses = [];
+
+	for (const combo of combinations) {
+		combinationClasses = [...combinationClasses, processCombination(partName, combo, attributes, manifest)];
+	}
+
+	return clsx(
+		unifyClasses(baseBaseClasses),
+		unifyClasses(baseEditorClasses),
+		...optionClasses,
+		...combinationClasses,
+		...custom,
+	);
+};