Released version 4.2 with a lot of changes

Author: TwistedAndy

README.md

@@ -1,19 +1,71 @@
-# Twee 4.1
-
-**Twee** is the advanced WordPress starter theme focused on simplifying the theme development and support
+# Twee 4.2
 
+**Twee** is a powerful WordPress theme framework built for high-performance, large-scale projects. It is finely tuned for Advanced Custom Fields, features an
+alternative metadata storage API, and leverages object caching to minimize database load and maximize speed.
 
 ## Features
 
-* Asset management library allowing to manage scripts, stylesheets, and localization strings
-* Resize and cache thumbnails with or without registering a new image size
-* Base widget class with custom settings
-* Taxonomy and terms processing libraries
-* Breadcrumbs with built-in JSON-LD and microdata support
-* Pagination with custom query support
-* Modules to load more posts and process the contact form with attachments
-* One file configuration. It allows you to specify all your image sizes, assets, menu locations, sidebars, custom post types, taxonomies, and other things in
-  one place
+### 1. Ultrafast Metadata Storage for Advanced Custom Fields
+
+- Stores metadata for Repeater, Group, or Clone fields in a single row instead of multiple rows
+- Fully compatible with the WordPress Metadata API, even for complex field types
+- Stores field keys in a single field, instead of duplicating keys for each row as in the default ACF behavior
+- Fully supports the ACF API and all ACF plugins
+- Enables dynamic rendering for ACF Flexible Content fields when using the ACF Extended plugin
+- Supports automatic section preview generation for ACF Flexible Content fields via Puppeteer
+
+### 2. Highly Optimized Metadata API
+
+- Includes a performance-optimized metadata API that remains fully compatible with WordPress
+- Reduces heavy database queries by preloading metadata into memory
+- Uses cache partitioning to minimize data transfer from cache
+- Implements advanced techniques like binary search to speed up metadata access
+- Fully integrates with WordPress metadata caching
+- Performs fast metadata updates by checking for changes before writing to the database
+
+### 3. High-Performance Post and Term Libraries
+
+- Enables bulk fetching of post data to avoid N+1 query issues
+- Retrieves post terms and term posts in a single request for improved performance
+- Builds and caches term trees, with the ability to flatten them if needed
+- Includes term threading to easily retrieve full parent-child term hierarchies
+- Supports fetching post IDs associated with specific terms
+
+### 4. Advanced Asset Management
+
+- Automatically scans, resolves, and registers assets and their dependencies
+- Includes only required styles based on section class names
+- Injects essential base styles and fonts into the head for improved loading speed
+- Automates versioning to eliminate manual version bumps when unnecessary
+- Loads required assets for Flexible Content section previews automatically
+
+### 5. Efficient Image Processing and Thumbnail Generation
+
+- Supports hidden image sizes that generate thumbnails on demand to avoid clutter
+- Integrates with popular image minification plugins for optimized output
+- Allows SVG uploads and generates proper metadata
+- Automatically generates correct srcset and sizes based on layout settings
+- Uses high-performance caching for faster thumbnail generation
+- Provides built-in WebP conversion support
+
+### 6. Additional Tools and Utilities
+
+- Includes a custom pagination library with support for custom queries
+- Offers a breadcrumbs library with JSON-LD structured data support
+- Fixes common accessibility issues in menus
+- Built-in Load More post handler for dynamic content loading
+- Integrated logging system with WooCommerce compatibility
+- Provides a base class for building widgets
+- Centralized configuration within functions.php for easy management
+
+### 7. Build Tools and Styles
+
+- Uses Gulp to build all assets, automatically generating separate block styles, injecting CSS properties into the head, and applying additional optimizations
+- Assumes that all styles for a single block are located in one SCSS or CSS file, with the base class ending in _box. Learn more about this approach
+  here: [CSS_BOX: A Better Way to Write CSS](https://www.reddit.com/r/css/comments/1apomz1/css_box_a_better_way_to_write_css/)
+- The HTML/CSS starter kit is available in a separate repository: [CSS_BOX Starter Kit](https://github.com/TwistedAndy/starter-kit)
+- Uses the Bigger Picture library for popup images and videos: [Bigger Picture](https://github.com/TwistedAndy/bigger-picture). This library is optimized for
+  maximum browser performance and a smooth user experience
 
 
 ## About

theme/includes/core/app.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 global $twee_cache;

theme/includes/core/asset.php

@@ -4,14 +4,27 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**
- * Register assets from the plugins and blocks folders
+ * Add an asset placeholder
+ */
+add_action('wp_head', 'tw_asset_placeholder', 6);
+
+
+/**
+ * Scan and register assets from the plugins and blocks folders
+ * It's important to do this before the 'wp_enqueue_scripts' call
  */
-add_action('init', function() {
+add_action('wp_head', 'tw_asset_init', 0);
+add_action('admin_enqueue_scripts', 'tw_asset_init', 0);
+
+function tw_asset_init() {
 
+	/**
+	 * Register assets from the plugins folder
+	 */
 	$base = TW_ROOT . 'assets/plugins/';
 
 	$files = scandir($base);
@@ -54,6 +67,9 @@
 
 	}
 
+	/**
+	 * Register styles from the blocks folder
+	 */
 	$base = TW_ROOT . 'assets/build/blocks/';
 
 	$files = scandir($base);
@@ -93,22 +109,56 @@
 		return;
 	}
 
-	tw_app_set('registered', $assets, 'assets');
+	/**
+	 * Normalize assets and collect dependencies
+	 */
+	$available = [
+		'style' => [],
+		'script' => [],
+	];
 
 	foreach ($assets as $name => $asset) {
 
 		if (!is_string($name) or empty($asset)) {
+			unset($assets[$name]);
 			continue;
 		}
 
 		$asset = tw_asset_normalize($asset);
 
 		if (!is_array($asset)) {
-			continue;
+			unset($assets[$name]);
+		}
+
+		if (!empty($asset['style'])) {
+			$available['style'][] = $name;
+		}
+
+		if (!empty($asset['script'])) {
+			$available['script'][] = $name;
 		}
 
 		$assets[$name] = $asset;
 
+	}
+
+	tw_app_set('registered', $assets, 'assets');
+
+	/**
+	 * Check dependencies and register assets in WordPress
+	 */
+	foreach ($assets as $name => $asset) {
+
+		/**
+		 * Remove unavailable internal dependencies
+		 */
+		foreach ($asset['deps'] as $type => $deps) {
+			if ($deps and array_diff($deps, $available[$type])) {
+				$asset['deps'][$type] = array_intersect($deps, $available[$type]);
+				$assets[$name] = $asset;
+			}
+		}
+
 		if (!empty($asset['prefix'])) {
 			$asset_name = $asset['prefix'] . $name;
 		} else {
@@ -173,13 +223,7 @@
 		ob_start('tw_asset_inject');
 	}
 
-}, 30);
-
-
-/**
- * Add an asset placeholder
- */
-add_action('wp_head', 'tw_asset_placeholder', 6);
+}
 
 
 /**

theme/includes/core/content.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**
@@ -39,17 +39,17 @@ function tw_content_title($object, $length = 0) {
 
 
 /**
- * Get the short description for a given post or text
+ * Get a short description for a given object or a string
  *
- * @param bool|string|WP_Post|WP_Term|WP_User $object       Post or text to find and strip the text
- * @param int                                 $length       Required length of the text
- * @param bool|string                         $allowed_tags List of tags separated by "|"
- * @param string                              $find         Symbol to find for proper strip
- * @param bool                                $force_cut    Strip the post excerpt
+ * @param string|WP_Post|WP_Term|WP_User $object       Post, Term, User, or a string
+ * @param int                            $length       Required length of the text
+ * @param bool|string                    $allowed_tags List of tags separated by "|"
+ * @param string                         $find         Symbol to find for proper strip
+ * @param bool                           $force_cut    Strip the post excerpt
  *
  * @return bool|string
  */
-function tw_content_text($object = false, $length = 250, $allowed_tags = false, $find = ' ', $force_cut = true) {
+function tw_content_text($object, $length = 250, $allowed_tags = false, $find = ' ', $force_cut = true) {
 
 	$excerpt = false;
 	$text = '';
@@ -131,29 +131,27 @@ function tw_content_link($link, $class = 'button', $hidden = '') {
 
 	$result = '';
 
-	if (is_array($link) and !empty($link['url']) and isset($link['title'])) {
-
-		if ($class) {
-			$class = ' class="' . $class . '"';
-		} else {
-			$class = '';
-		}
-
-		if (!empty($link['target'])) {
-			$target = ' target="' . $link['target'] . '"';
-		} else {
-			$target = '';
-		}
+	if (!is_array($link) or empty($link['url']) or !isset($link['title'])) {
+		return $result;
+	}
 
-		if ($hidden) {
-			$hidden = '<span class="sr-hidden">' . $hidden . '</span>';
-		}
+	if ($class) {
+		$class = ' class="' . $class . '"';
+	} else {
+		$class = '';
+	}
 
-		$result = '<a href="' . esc_url($link['url']) . '"' . $class . $target . '>' . $link['title'] . $hidden . '</a>';
+	if (!empty($link['target'])) {
+		$target = ' target="' . $link['target'] . '"';
+	} else {
+		$target = '';
+	}
 
+	if ($hidden) {
+		$hidden = '<span class="sr-hidden">' . $hidden . '</span>';
 	}
 
-	return $result;
+	return '<a href="' . esc_url($link['url']) . '"' . $class . $target . '>' . $link['title'] . $hidden . '</a>';
 
 }
 

theme/includes/core/image.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**

theme/includes/core/legacy.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**

theme/includes/core/logger.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**

theme/includes/core/widget.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 namespace Twee;

theme/includes/theme/acfe.php

@@ -10,7 +10,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**

theme/includes/theme/block.php

@@ -4,7 +4,7 @@
  *
  * @author  Andrii Toniievych <toniyevych@gmail.com>
  * @package Twee
- * @version 4.1
+ * @version 4.2
  */
 
 /**