9.2.0

CHANGELOG.md

@@ -3,6 +3,15 @@ All notable changes to this project will be documented in this file.
 
 This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).
 
+## [9.2.0]
+
+### Added
+- Introduced new, more flexible, and simpler to use `tailwindClasses` function. Replaces `getTwPart`, `getTwDynamicPart`, and `getTwClasses`.
+	- **Potentially breaking**: `twClassesEditor` is now appended to `twClasses`. If you need editor-only classes, you can now use the `twClassesEditorOnly` key. Editor-only classes replace `twClasses`, but will also have classes from `twClassesEditor`.
+	- **Potentially breaking**: `parts` key in manifest now supports specifying multiple parts just with a comma-separated string.
+	- You can now apply classes to multiple parts within one option or combination! Also work with responsive options.
+	- There are now (basic) warnings for misconfigurations of parts and options.
+
 ## [9.1.6]
 
 ### Fixed
@@ -663,6 +672,7 @@ Init setup
 
 [Unreleased]: https://github.com/infinum/eightshift-libs/compare/main...HEAD
 
+[9.2.0]: https://github.com/infinum/eightshift-libs/compare/9.1.6...9.2.0
 [9.1.6]: https://github.com/infinum/eightshift-libs/compare/9.1.5...9.1.6
 [9.1.5]: https://github.com/infinum/eightshift-libs/compare/9.1.4...9.1.5
 [9.1.4]: https://github.com/infinum/eightshift-libs/compare/9.1.3...9.1.4

src/Helpers/TailwindTrait.php

@@ -10,6 +10,9 @@
 
 namespace EightshiftLibs\Helpers;
 
+use Exception;
+use JsonException;
+
 /**
  * Class TailwindTrait Helper.
  */
@@ -40,6 +43,8 @@ public static function getTwBreakpoints($desktopFirst = false)
 	}
 
 	/**
+	 * @deprecated 9.2.0 Use `tailwindClasses` instead.
+	 *
 	 * Gets Tailwind classes for the provided part.
 	 *
 	 * The part needs to be defined within the manifest, in the `tailwind` object.
@@ -66,6 +71,8 @@ public static function getTwPart($part, $manifest, ...$custom)
 	}
 
 	/**
+	 * @deprecated 9.2.0 Use `tailwindClasses` instead.
+	 *
 	 * Gets Tailwind classes for the provided dynamic part.
 	 *
 	 * The part needs to be defined within the manifest, in the `tailwind` object.
@@ -164,6 +171,8 @@ public static function getTwDynamicPart($part, $attributes, $manifest, ...$custo
 	}
 
 	/**
+	 * @deprecated 9.2.0 Use `tailwindClasses` instead.
+	 *
 	 * Get Tailwind classes for the given component/block.
 	 *
 	 * @param array<mixed> $attributes Component/block attributes.
@@ -289,4 +298,168 @@ public static function getTwClasses($attributes, $manifest, ...$custom)
 
 		return Helpers::classnames([$baseClasses, ...$mainClasses, ...$combinationClasses, ...$custom]);
 	}
+
+	private static function unifyClasses($input)
+	{
+		if (\is_array($input)) {
+			return Helpers::classnames($input);
+		}
+
+		return trim($input);
+	}
+
+	private static function processOption($partName, $optionValue, $defs)
+	{
+		$optionClasses = [];
+
+		$isResponsive = $defs['responsive'] ?? false;
+		$itemPartName = isset($defs['part']) ? $defs['part'] : 'base';
+		$isSingleValue = isset($defs['twClasses']) || isset($defs['twClassesEditor']);
+
+		// Part checks.
+		if (!$isSingleValue && !isset($defs[$partName])) {
+			return '';
+		}
+
+		if ($isSingleValue && !str_contains($itemPartName, $partName)) {
+			return '';
+		}
+
+		// Non-responsive options.
+		if (!$isResponsive) {
+			$rawValue = $defs['twClasses'][$optionValue] ?? $defs[$partName]['twClasses'][$optionValue] ?? '';
+
+			return self::unifyClasses($rawValue);
+		}
+
+		// Responsive options.
+		$breakpoints = array_keys($optionValue);
+
+		if (in_array('_desktopFirst', $breakpoints, true)) {
+			$breakpoints = array_filter($breakpoints, fn($breakpoint) => $breakpoint !== '_desktopFirst');
+		}
+
+		foreach ($breakpoints as $breakpoint) {
+			$breakpointValue = $optionValue[$breakpoint];
+
+			if (!$breakpointValue) {
+				continue;
+			}
+
+			$rawValue = $defs['twClasses'][$breakpointValue] ?? $defs[$partName]['twClasses'][$breakpointValue] ?? '';
+			$rawClasses = self::unifyClasses($rawValue);
+
+			if ($breakpoint === '_default') {
+				$optionClasses[] = $rawClasses;
+
+				continue;
+			}
+
+			$splitClasses = explode(' ', $rawClasses);
+			$splitClasses = array_map(fn($cn) => empty($cn) ? null : "{$breakpoint}:{$cn}", $splitClasses);
+
+			$optionClasses = [...$optionClasses, ...$splitClasses];
+		}
+
+		return self::unifyClasses($optionClasses);
+	}
+
+	private static function processCombination($partName, $combo, $attributes, $manifest)
+	{
+		$matches = true;
+
+		foreach ($combo['attributes'] as $attributeName => $allowedValue) {
+			$optionValue = Helpers::checkAttr($attributeName, $attributes, $manifest, true);
+
+			if (\is_bool($optionValue)) {
+				$optionValue = $optionValue ? 'true' : 'false';
+			}
+
+			if (is_array($allowedValue) && !in_array($optionValue, $allowedValue, true)) {
+				$matches = false;
+				break;
+			}
+
+			if ($optionValue !== $allowedValue) {
+				$matches = false;
+				break;
+			}
+		}
+
+		if (!$matches) {
+			return '';
+		}
+
+		$itemPartName = isset($combo['part']) ? $combo['part'] : 'base';
+		$isSingleValue = isset($combo['twClasses']) || isset($combo['twClassesEditor']);
+
+		if ($isSingleValue && !str_contains($itemPartName, $partName)) {
+			return '';
+		}
+
+		$rawValue = $combo['output'][$partName]['twClasses'] ?? $combo['twClasses'] ?? '';
+
+		if (is_array($rawValue) && !\array_is_list($rawValue)) {
+			throw new JsonException('Combination was not defined correctly. Please check the combination definition in the manifest.');
+		}
+
+		return self::unifyClasses($rawValue);
+	}
+
+	/**
+	 * Get Tailwind classes for the given component/block.
+	 *
+	 * @param string $string Part to get classes for.
+	 * @param array<mixed> $attributes Component/block attributes.
+	 * @param array<mixed> $manifest Component/block manifest data.
+	 * @param array<string> ...$custom Additional custom classes.
+	 *
+	 * @return string
+	 */
+	public static function tailwindClasses($part, $attributes, $manifest, ...$custom)
+	{
+		// If nothing is set, return custom classes as a fallback.
+		if (!$attributes || !$manifest || !isset($manifest['tailwind']) || \array_keys($manifest['tailwind']) === []) {
+			return $custom ? Helpers::classnames($custom) : ''; // @phpstan-ignore-line
+		}
+
+		$allParts = isset($manifest['tailwind']['parts']) ? ['base', ...array_keys($manifest['tailwind']['parts'])] : ['base'];
+
+		$partName = 'base';
+
+		if (!empty($part) && isset($manifest['tailwind']['parts'][$part]) && in_array($part, $allParts, true)) {
+			$partName = $part;
+		} elseif ($part !== 'base') {
+			throw new Exception("Part '{$part}' is not defined in the manifest.");
+		}
+
+		// Base classes.
+		$baseClasses = self::unifyClasses($manifest['tailwind']['parts'][$partName]['twClasses'] ?? $manifest['tailwind']['base']['twClasses'] ?? ['']);
+
+		// Option classes.
+		$options = $manifest['tailwind']['options'] ?? [];
+
+		$optionClasses = [];
+
+		foreach ($options as $attributeName => $defs) {
+			$optionValue = Helpers::checkAttr($attributeName, $attributes, $manifest, true);
+
+			if (\is_bool($optionValue)) {
+				$optionValue = $optionValue ? 'true' : 'false';
+			}
+
+			$optionClasses[] = self::processOption($partName, $optionValue, $defs);
+		}
+
+		// Combinations.
+		$combinations = $manifest['tailwind']['combinations'] ?? [];
+
+		$combinationClasses = [];
+
+		foreach ($combinations as $combo) {
+			$combinationClasses[] = self::processCombination($partName, $combo, $attributes, $manifest);
+		}
+
+		return Helpers::classnames([$baseClasses, ...$optionClasses, ...$combinationClasses, ...$custom]);
+	}
 }