Update 2024-07-20 22:43:12

src/355bf21a-f859-4528-9110-bcd2c6d05ea7/code.php

@@ -87,18 +87,35 @@ final class Grep extends ExtendingGrep implements GrepInterface
 			$path_guid = $path->guid ?? null;
 			if ($path_guid !== null)
 			{
+				// get the Settings meta
 				if (($meta = $this->contents->metadata($path->organisation, $path->repository, $path->index->{$guid}->path . '/item.json', $branch)) !== null &&
 					isset($meta->sha))
 				{
 					if (isset($power->params) && is_object($power->params) &&
 						isset($power->params->source) && is_array($power->params->source))
 					{
-						$power->params->source[$path_guid] = $meta->sha;
+						$power->params->source[$path_guid . '-settings'] = $meta->sha;
 					}
 					else
 					{
 						$power->params = (object) [
-							'source' => [$path_guid => $meta->sha]
+							'source' => [$path_guid . '-settings' => $meta->sha]
+						];
+					}
+				}
+				// get the README meta
+				if (($meta = $this->contents->metadata($path->organisation, $path->repository, $path->index->{$guid}->path . '/README.md', $branch)) !== null &&
+					isset($meta->sha))
+				{
+					if (isset($power->params) && is_object($power->params) &&
+						isset($power->params->source) && is_array($power->params->source))
+					{
+						$power->params->source[$path_guid . '-readme'] = $meta->sha;
+					}
+					else
+					{
+						$power->params = (object) [
+							'source' => [$path_guid . '-readme' => $meta->sha]
 						];
 					}
 				}

src/355bf21a-f859-4528-9110-bcd2c6d05ea7/code.power

@@ -56,18 +56,35 @@
 			$path_guid = $path->guid ?? null;
 			if ($path_guid !== null)
 			{
+				// get the Settings meta
 				if (($meta = $this->contents->metadata($path->organisation, $path->repository, $path->index->{$guid}->path . '/item.json', $branch)) !== null &&
 					isset($meta->sha))
 				{
 					if (isset($power->params) && is_object($power->params) &&
 						isset($power->params->source) && is_array($power->params->source))
 					{
-						$power->params->source[$path_guid] = $meta->sha;
+						$power->params->source[$path_guid . '-settings'] = $meta->sha;
 					}
 					else
 					{
 						$power->params = (object) [
-							'source' => [$path_guid => $meta->sha]
+							'source' => [$path_guid . '-settings' => $meta->sha]
+						];
+					}
+				}
+				// get the README meta
+				if (($meta = $this->contents->metadata($path->organisation, $path->repository, $path->index->{$guid}->path . '/README.md', $branch)) !== null &&
+					isset($meta->sha))
+				{
+					if (isset($power->params) && is_object($power->params) &&
+						isset($power->params->source) && is_array($power->params->source))
+					{
+						$power->params->source[$path_guid . '-readme'] = $meta->sha;
+					}
+					else
+					{
+						$power->params = (object) [
+							'source' => [$path_guid . '-readme' => $meta->sha]
 						];
 					}
 				}

src/3730a000-ab64-477d-8b0f-70eaf71b517a/code.php

@@ -345,7 +345,9 @@ final class JoomlaPower implements PowerInterface
 	 */
 	private function setNamespaceAndType(string $guid, array $namespace): void
 	{
-		$this->active[$guid]->namespace = $namespace['namespace'];
+		$this->active[$guid]->namespace = $this->placeholder->update_(
+			$namespace['namespace']
+		);
 		$this->active[$guid]->type = $namespace['type'] ?? 'class';
 	}
 

src/3730a000-ab64-477d-8b0f-70eaf71b517a/code.power

@@ -309,7 +309,9 @@
 	 */
 	private function setNamespaceAndType(string $guid, array $namespace): void
 	{
-		$this->active[$guid]->namespace = $namespace['namespace'];
+		$this->active[$guid]->namespace = $this->placeholder->update_(
+			$namespace['namespace']
+		);
 		$this->active[$guid]->type = $namespace['type'] ?? 'class';
 	}
 

src/39a75870-a7f7-45fd-937d-5ba97b85b8ad/code.php

@@ -12,8 +12,8 @@
 namespace VDM\Joomla\Componentbuilder\JoomlaPower\Remote;
 
 
-use VDM\Joomla\Interfaces\Data\RemoteGetInterface;
+use VDM\Joomla\Interfaces\Remote\GetInterface;
-use VDM\Joomla\Data\Remote\Get as ExtendingGet;
+use VDM\Joomla\Abstraction\Remote\Get as ExtendingGet;
 
 
 /**
@@ -21,7 +21,7 @@ use VDM\Joomla\Data\Remote\Get as ExtendingGet;
  * 
  * @since 3.2.0
  */
-final class Get extends ExtendingGet implements RemoteGetInterface
+final class Get extends ExtendingGet implements GetInterface
 {
 	/**
 	 * Table Name

src/3ab0eba9-f37b-4b37-aec1-2e78067f2aff/code.php

@@ -12,8 +12,8 @@
 namespace VDM\Joomla\Componentbuilder\Power\Remote;
 
 
-use VDM\Joomla\Interfaces\Data\RemoteGetInterface;
+use VDM\Joomla\Interfaces\Remote\GetInterface;
-use VDM\Joomla\Data\Remote\Get as ExtendingGet;
+use VDM\Joomla\Abstraction\Remote\Get as ExtendingGet;
 
 
 /**
@@ -21,7 +21,7 @@ use VDM\Joomla\Data\Remote\Get as ExtendingGet;
  * 
  * @since 3.2.0
  */
-final class Get extends ExtendingGet implements RemoteGetInterface
+final class Get extends ExtendingGet implements GetInterface
 {
 	/**
 	 * Table Name

src/85cddb24-7ee6-4d86-a0db-615f443e1aec/README.md

@@ -14,9 +14,12 @@
 @startuml
 class Set << (F,LightGreen) >> #RoyalBlue {
   # string $table
+  # string $area
   # array $map
   # updateItem(object $item, object $existing, ...) : bool
   # createItem(object $item, object $repo) : void
+  # updateItemReadme(object $item, object $existing, ...) : void
+  # createItemReadme(object $item, object $repo) : void
 }
 
 note right of Set::updateItem
@@ -37,6 +40,25 @@ note right of Set::createItem
   since: 3.2.2
   return: void
 end note
+
+note right of Set::updateItemReadme
+  update an existing item readme
+
+  since: 3.2.2
+  return: void
+  
+  arguments:
+    object $item
+    object $existing
+    object $repo
+end note
+
+note right of Set::createItemReadme
+  create a new item readme
+
+  since: 3.2.2
+  return: void
+end note
  
 @enduml
 ```

src/85cddb24-7ee6-4d86-a0db-615f443e1aec/code.php

@@ -12,8 +12,8 @@
 namespace VDM\Joomla\Componentbuilder\JoomlaPower\Remote;
 
 
-use VDM\Joomla\Interfaces\Data\RemoteSetInterface;
+use VDM\Joomla\Interfaces\Remote\SetInterface;
-use VDM\Joomla\Data\Remote\Set as ExtendingSet;
+use VDM\Joomla\Abstraction\Remote\Set as ExtendingSet;
 
 
 /**
@@ -21,16 +21,32 @@ use VDM\Joomla\Data\Remote\Set as ExtendingSet;
  * 
  * @since 3.2.2
  */
-final class Set extends ExtendingSet implements RemoteSetInterface
+final class Set extends ExtendingSet implements SetInterface
 {
 	/**
 	 * Table Name
 	 *
 	 * @var    string
-	 * @since 3.2.1
+	 * @since 3.2.2
 	 */
 	protected string $table = 'joomla_power';
 
+	/**
+	 * Area Name
+	 *
+	 * @var    string
+	 * @since 3.2.2
+	 */
+	protected string $area = 'Joomla Power';
+
+	/**
+	 * Prefix Key
+	 *
+	 * @var    string
+	 * @since 3.2.2
+	 */
+	protected string $prefix_key = 'Joomla---';
+
 	/**
 	 * The item map
 	 *
@@ -45,12 +61,18 @@ final class Set extends ExtendingSet implements RemoteSetInterface
 	];
 
 	/**
-	 * The settings file path
+	 * The index map
 	 *
-	 * @var   string
+	 * @var    array
 	 * @since 3.2.2
 	 */
-	protected string $settings_path = 'item.json';
+	protected array $index_map = [
+		'name' => 'index_map_IndexName',
+		'settings' => 'index_map_IndexSettingsPath',
+		'path' => 'index_map_IndexPath',
+		'jpk' => 'index_map_IndexKey',
+		'guid' => 'index_map_IndexGUID'
+	];
 
 	/**
 	 * update an existing item (if changed)
@@ -65,7 +87,7 @@ final class Set extends ExtendingSet implements RemoteSetInterface
 	protected function updateItem(object $item, object $existing, object $repo): bool
 	{
 		// make sure there was a change
-		$sha = $existing->params->source[$repo->guid] ?? null;
+		$sha = $existing->params->source[$repo->guid . '-settings'] ?? null;
 		$existing = $this->mapItem($existing);
 		if ($sha === null || $this->areObjectsEqual($item, $existing))
 		{
@@ -104,6 +126,57 @@ final class Set extends ExtendingSet implements RemoteSetInterface
 			'Create ' . $item->system_name, // The commit message.
 			$repo->write_branch // The branch name.
 		);
+	}
+
+	/**
+	 * update an existing item readme
+	 *
+	 * @param object $item
+	 * @param object $existing
+	 * @param object $repo
+	 *
+	 * @return void
+	 * @since 3.2.2
+	 */
+	protected function updateItemReadme(object $item, object $existing, object $repo): void
+	{
+		// make sure there was a change
+		$sha = $existing->params->source[$repo->guid . '-readme'] ?? null;
+		if ($sha === null)
+		{
+			return;
+		}
+
+		$this->git->update(
+			$repo->organisation, // The owner name.
+			$repo->repository, // The repository name.
+			'src/' . $item->guid . '/README.md', // The file path.
+			$this->itemReadme->get($item), // The file content.
+			'Update ' . $item->system_name . ' readme file', // The commit message.
+			$sha, // The blob SHA of the old file.
+			$repo->write_branch // The branch name.
+		);
+	}
+
+	/**
+	 * create a new item readme
+	 *
+	 * @param object  $item
+	 * @param object  $repo
+	 *
+	 * @return void
+	 * @since 3.2.2
+	 */
+	protected function createItemReadme(object $item, object $repo): void
+	{
+		$this->git->create(
+			$repo->organisation, // The owner name.
+			$repo->repository, // The repository name.
+			'src/' . $item->guid . '/README.md', // The file path.
+			$this->itemReadme->get($item), // The file content.
+			'Create ' . $item->system_name . ' readme file', // The commit message.
+			$repo->write_branch // The branch name.
+		);
 	}
 }
 

src/85cddb24-7ee6-4d86-a0db-615f443e1aec/code.power

@@ -2,10 +2,26 @@
 	 * Table Name
 	 *
 	 * @var    string
-	 * @since 3.2.1
+	 * @since 3.2.2
 	 */
 	protected string $table = 'joomla_power';
 
+	/**
+	 * Area Name
+	 *
+	 * @var    string
+	 * @since 3.2.2
+	 */
+	protected string $area = 'Joomla Power';
+
+	/**
+	 * Prefix Key
+	 *
+	 * @var    string
+	 * @since 3.2.2
+	 */
+	protected string $prefix_key = 'Joomla---';
+
 	/**
 	 * The item map
 	 *
@@ -20,12 +36,18 @@
 	];
 
 	/**
-	 * The settings file path
+	 * The index map
 	 *
-	 * @var   string
+	 * @var    array
 	 * @since 3.2.2
 	 */
-	protected string $settings_path = 'item.json';
+	protected array $index_map = [
+		'name' => 'index_map_IndexName',
+		'settings' => 'index_map_IndexSettingsPath',
+		'path' => 'index_map_IndexPath',
+		'jpk' => 'index_map_IndexKey',
+		'guid' => 'index_map_IndexGUID'
+	];
 
 	/**
 	 * update an existing item (if changed)
@@ -40,7 +62,7 @@
 	protected function updateItem(object $item, object $existing, object $repo): bool
 	{
 		// make sure there was a change
-		$sha = $existing->params->source[$repo->guid] ?? null;
+		$sha = $existing->params->source[$repo->guid . '-settings'] ?? null;
 		$existing = $this->mapItem($existing);
 		if ($sha === null || $this->areObjectsEqual($item, $existing))
 		{
@@ -79,4 +101,55 @@
 			'Create ' . $item->system_name, // The commit message.
 			$repo->write_branch // The branch name.
 		);
+	}
+
+	/**
+	 * update an existing item readme
+	 *
+	 * @param object $item
+	 * @param object $existing
+	 * @param object $repo
+	 *
+	 * @return void
+	 * @since 3.2.2
+	 */
+	protected function updateItemReadme(object $item, object $existing, object $repo): void
+	{
+		// make sure there was a change
+		$sha = $existing->params->source[$repo->guid . '-readme'] ?? null;
+		if ($sha === null)
+		{
+			return;
+		}
+
+		$this->git->update(
+			$repo->organisation, // The owner name.
+			$repo->repository, // The repository name.
+			'src/' . $item->guid . '/README.md', // The file path.
+			$this->itemReadme->get($item), // The file content.
+			'Update ' . $item->system_name . ' readme file', // The commit message.
+			$sha, // The blob SHA of the old file.
+			$repo->write_branch // The branch name.
+		);
+	}
+
+	/**
+	 * create a new item readme
+	 *
+	 * @param object  $item
+	 * @param object  $repo
+	 *
+	 * @return void
+	 * @since 3.2.2
+	 */
+	protected function createItemReadme(object $item, object $repo): void
+	{
+		$this->git->create(
+			$repo->organisation, // The owner name.
+			$repo->repository, // The repository name.
+			'src/' . $item->guid . '/README.md', // The file path.
+			$this->itemReadme->get($item), // The file content.
+			'Create ' . $item->system_name . ' readme file', // The commit message.
+			$repo->write_branch // The branch name.
+		);
 	}

src/aca1e57d-6fe8-4bad-bd39-7ebac333ac6e/README.md

@@ -16,16 +16,12 @@ class Main << (F,LightGreen) >> #RoyalBlue {
   - readmeBuilder($items) : string
   - readmeModel(array $classes) : string
   - generateIndex(array $classes) : string
-  - defineTypeOrder() : array
+  - sortClasses(array $classes) : void
-  - sortClasses(array $classes, array $typeOrder) : void
-  - compareNamespace(array $a, array $b) : int
-  - compareType(array $a, array $b, ...) : int
   - compareName(array $a, array $b) : int
   - indexLinkPower(array $power) : string
   - linkPowerRepo(array $power) : string
-  - linkPowerCode(array $power) : string
   - linkPowerSettings(array $power) : string
-  - linkPowerSPK(array $power) : string
+  - linkPowerJPK(array $power) : string
 }
 
 note right of Main::get
@@ -55,67 +51,34 @@ note left of Main::generateIndex
   return: string
 end note
 
-note right of Main::defineTypeOrder
+note right of Main::sortClasses
-  Define the order of types for sorting purposes
-
-  since: 3.2.0
-  return: array
-end note
-
-note left of Main::sortClasses
   Sort the flattened array using a single sorting function
 
   since: 3.2.0
   return: void
 end note
 
-note right of Main::compareNamespace
+note left of Main::compareName
-  Compare the namespace of two classes
-
-  since: 3.2.0
-  return: int
-end note
-
-note left of Main::compareType
-  Compare the type of two classes
-
-  since: 3.2.0
-  return: int
-  
-  arguments:
-    array $a
-    array $b
-    array $typeOrder
-end note
-
-note right of Main::compareName
   Compare the name of two classes
 
   since: 3.2.0
   return: int
 end note
 
-note left of Main::indexLinkPower
+note right of Main::indexLinkPower
   Build the Link to the power in this repository
 
   since: 3.2.0
   return: string
 end note
 
-note right of Main::linkPowerRepo
+note left of Main::linkPowerRepo
   Build the Link to the power in this repository
 
   since: 3.2.0
   return: string
 end note
 
-note left of Main::linkPowerCode
-  Build the Link to the power settings in this repository
-
-  since: 3.2.0
-  return: string
-end note
-
 note right of Main::linkPowerSettings
   Build the Link to the power settings in this repository
 
@@ -123,8 +86,8 @@ note right of Main::linkPowerSettings
   return: string
 end note
 
-note left of Main::linkPowerSPK
+note left of Main::linkPowerJPK
-  Get the SuperPowerKey (SPK)
+  Get the JoomlaPowerKey (JPK)
 
   since: 3.2.0
   return: string

src/aca1e57d-6fe8-4bad-bd39-7ebac333ac6e/code.php

@@ -48,7 +48,12 @@ final class Main implements MainInterface
 ```"];
 
 		// default description of super powers
-		$readme[] = "\n### What is JCB Joomla Powers?\nThe Joomla Component Builder (JCB) Joomla Power features are designed to enhance JCB's functionality and streamline the development process. These Joomla Powers enable developers to efficiently manage and share their custom powers across multiple JCB instances through repositories hosted on [https://git.vdm.dev/[username]/[repository-name]](https://git.vdm.dev). JCB Super Powers are managed using a combination of layers, events, tasks, methods, switches, and algorithms, which work together to provide powerful customization and extensibility options. More details on JCB Super Powers can be found in the [Super Powers Documentation](https://git.vdm.dev/joomla/super-powers/wiki).\n\nIn summary, JCB Super Powers offer a flexible and efficient way to manage and share functionalities between JCB instances. By utilizing a sophisticated system of layers, events, tasks, methods, switches, and algorithms, developers can seamlessly integrate JCB core powers and their custom powers. For more information on how to work with JCB Super Powers, refer to the [Super Powers User Guide](https://git.vdm.dev/joomla/super-powers/wiki).\n\n### What can I find here?\nThis repository contains an index (see below) of all the approved powers within the JCB GUI. During the compilation of a component, these powers are automatically added to the repository, ensuring a well-organized and accessible collection of functionalities.\n";
+		$readme[] = "\n### What is JCB Joomla Powers?\nThe Joomla Component Builder (JCB) Joomla Power features are designed to enhance JCB's functionality and streamline the development process. The Joomla powers enable developers to effectively leverage Joomla classes in their custom code without needing to manually add the `use` statements for those classes to the file headers. JCB automatically updates these `use` statements in the necessary headers when it detects a Joomla power key in the custom code.\n
+\n
+By doing this, we can control the `use` statements dynamically from a central point. This is particularly beneficial when transitioning from Joomla 3 to Joomla 4, as it allows us to seamlessly switch from certain classes to their respective Joomla framework classes and vice versa. Maintaining these `use` statements in the Joomla Power area ensures that JCB handles the inclusion and updating of class names to prevent conflicts with other classes.\n
+\n
+This approach is convenient and allows developers to focus on the bespoke parts of their application logic without worrying about class declarations.\n
+\nThis repository contains an index (see below) of all the Joomla! Powers within the JCB core GUI. These Joomla! Powers are automatically added to the repository by our maintainers, ensuring a well-organized and accessible collection of Joomla Classes are maintained.\n";
 
 		// get the readme body
 		$readme[] = $this->readmeBuilder($items);
@@ -93,8 +98,6 @@ final class Main implements MainInterface
 		{
 			// add to the sort bucket
 			$classes[] = [
-				'namespace' => $power['namespace'],
-				'type' => $power['type'],
 				'name' => $power['name'],
 				'link' => $this->indexLinkPower($power)
 			];
@@ -113,7 +116,7 @@ final class Main implements MainInterface
 	 */
 	private function readmeModel(array &$classes): string
 	{
-		$this->sortClasses($classes, $this->defineTypeOrder());
+		$this->sortClasses($classes);
 
 		return $this->generateIndex($classes);
 	}
@@ -127,108 +130,34 @@ final class Main implements MainInterface
 	 */
 	private function generateIndex(array &$classes): string
 	{
-		$result = "# Index of powers\n";
+		$result = "# Index of Joomla! Powers\n";
-		$current_namespace = null;
 
 		foreach ($classes as $class)
 		{
-			if ($class['namespace'] !== $current_namespace)
-			{
-				$current_namespace = $class['namespace'];
-				$result .= "\n- **Namespace**: [{$current_namespace}](#" .
-					strtolower(str_replace('\\', '-', $current_namespace)) . ")\n";
-			}
-
 			// Add the class details
-			$result .= "\n  - " . $class['link'];
+			$result .= "\n - " . $class['link'];
 		}
 
-		return $result;
+		$result .= "\n> remember to replace the `---` with `___` in the JPK to activate that Joomla! Power in your code";
-	}
 
-	/**
+
-	 * Define the order of types for sorting purposes
+		return $result;
-	 *
-	 * @return array The order of types
-	 * @since 3.2.0
-	 */
-	private function defineTypeOrder(): array
-	{
-		return [
-			'interface' => 1,
-			'abstract' => 2,
-			'abstract class' => 2,
-			'final' => 3,
-			'final class' => 3,
-			'class' => 4,
-			'trait' => 5
-		];
 	}
 
 	/**
 	 * Sort the flattened array using a single sorting function
 	 *
 	 * @param array $classes The classes to sort
-	 * @param array $typeOrder The order of types
+	 *
 	 * @since 3.2.0
 	 */
-	private function sortClasses(array &$classes, array $typeOrder): void
+	private function sortClasses(array &$classes): void
 	{
-		usort($classes, function ($a, $b) use ($typeOrder) {
+		usort($classes, function ($a, $b) {
-			$namespaceDiff = $this->compareNamespace($a, $b);
-
-			if ($namespaceDiff !== 0)
-			{
-				return $namespaceDiff;
-			}
-
-			$typeDiff = $this->compareType($a, $b, $typeOrder);
-
-			if ($typeDiff !== 0)
-			{
-				return $typeDiff;
-			}
-
 			return $this->compareName($a, $b);
 		});
 	}
 
-	/**
-	 * Compare the namespace of two classes
-	 *
-	 * @param array $a First class
-	 * @param array $b Second class
-	 *
-	 * @return int Comparison result
-	 * @since 3.2.0
-	 */
-	private function compareNamespace(array $a, array $b): int
-	{
-		$namespaceDepthDiff = substr_count($a['namespace'], '\\') - substr_count($b['namespace'], '\\');
-
-		if ($namespaceDepthDiff === 0)
-		{
-			return strcmp($a['namespace'], $b['namespace']);
-		}
-
-		return $namespaceDepthDiff;
-	}
-
-	/**
-	 * Compare the type of two classes
-	 *
-	 * @param array $a First class
-	 * @param array $b Second class
-	 * @param array $typeOrder The order of types
-	 *
-	 * @return int Comparison result
-	 * @since 3.2.0
-	 */
-	private function compareType(array $a, array $b, array $typeOrder): int
-	{
-		return $typeOrder[$a['type']] <=> $typeOrder[$b['type']];
-	}
-
 	/**
 	 * Compare the name of two classes
 	 *
@@ -253,13 +182,11 @@ final class Main implements MainInterface
 	 */
 	private function indexLinkPower(array &$power): string
 	{
-		$type = $power['type'] ?? 'error';
 		$name = $power['name'] ?? 'error';
-		return '**' . $type . ' ' . $name . "** | "
+		return '**' . $name . "** | "
 			. $this->linkPowerRepo($power) . ' | '
-			. $this->linkPowerCode($power) . ' | '
+			. $this->linkPowerSettings($power) . ' | JPK: `'
-			. $this->linkPowerSettings($power) . ' | '
+			. $this->linkPowerJPK($power) .'`';
-			. $this->linkPowerSPK($power);
 	}
 
 	/**
@@ -276,20 +203,6 @@ final class Main implements MainInterface
 		return '[Details](' . $path . ')';
 	}
 
-	/**
-	 * Build the Link to the power settings in this repository
-	 *
-	 * @param array  $power  The power details.
-	 *
-	 * @return string
-	 * @since 3.2.0
-	 */
-	private function linkPowerCode(array &$power): string
-	{
-		$code = $power['code'] ?? 'error';
-		return '[Code](' . $code . ')';
-	}
-
 	/**
 	 * Build the Link to the power settings in this repository
 	 *
@@ -305,17 +218,17 @@ final class Main implements MainInterface
 	}
 
 	/**
-	 * Get the SuperPowerKey (SPK)
+	 * Get the JoomlaPowerKey (JPK)
 	 *
 	 * @param array  $power  The power details.
 	 *
 	 * @return string
 	 * @since 3.2.0
 	 */
-	private function linkPowerSPK(array &$power): string
+	private function linkPowerJPK(array &$power): string
 	{
-		$spk = $power['spk'] ?? 'error';
+		$jpk = $power['jpk'] ?? 'error';
-		return $spk;
+		return $jpk;
 	}
 }
 

src/aca1e57d-6fe8-4bad-bd39-7ebac333ac6e/code.power

@@ -25,7 +25,12 @@
 ```"];
 
 		// default description of super powers
-		$readme[] = "\n### What is JCB Joomla Powers?\nThe Joomla Component Builder (JCB) Joomla Power features are designed to enhance JCB's functionality and streamline the development process. These Joomla Powers enable developers to efficiently manage and share their custom powers across multiple JCB instances through repositories hosted on [https://git.vdm.dev/[username]/[repository-name]](https://git.vdm.dev). JCB Super Powers are managed using a combination of layers, events, tasks, methods, switches, and algorithms, which work together to provide powerful customization and extensibility options. More details on JCB Super Powers can be found in the [Super Powers Documentation](https://git.vdm.dev/joomla/super-powers/wiki).\n\nIn summary, JCB Super Powers offer a flexible and efficient way to manage and share functionalities between JCB instances. By utilizing a sophisticated system of layers, events, tasks, methods, switches, and algorithms, developers can seamlessly integrate JCB core powers and their custom powers. For more information on how to work with JCB Super Powers, refer to the [Super Powers User Guide](https://git.vdm.dev/joomla/super-powers/wiki).\n\n### What can I find here?\nThis repository contains an index (see below) of all the approved powers within the JCB GUI. During the compilation of a component, these powers are automatically added to the repository, ensuring a well-organized and accessible collection of functionalities.\n";
+		$readme[] = "\n### What is JCB Joomla Powers?\nThe Joomla Component Builder (JCB) Joomla Power features are designed to enhance JCB's functionality and streamline the development process. The Joomla powers enable developers to effectively leverage Joomla classes in their custom code without needing to manually add the `use` statements for those classes to the file headers. JCB automatically updates these `use` statements in the necessary headers when it detects a Joomla power key in the custom code.\n
+\n
+By doing this, we can control the `use` statements dynamically from a central point. This is particularly beneficial when transitioning from Joomla 3 to Joomla 4, as it allows us to seamlessly switch from certain classes to their respective Joomla framework classes and vice versa. Maintaining these `use` statements in the Joomla Power area ensures that JCB handles the inclusion and updating of class names to prevent conflicts with other classes.\n
+\n
+This approach is convenient and allows developers to focus on the bespoke parts of their application logic without worrying about class declarations.\n
+\nThis repository contains an index (see below) of all the Joomla! Powers within the JCB core GUI. These Joomla! Powers are automatically added to the repository by our maintainers, ensuring a well-organized and accessible collection of Joomla Classes are maintained.\n";
 
 		// get the readme body
 		$readme[] = $this->readmeBuilder($items);
@@ -70,8 +75,6 @@
 		{
 			// add to the sort bucket
 			$classes[] = [
-				'namespace' => $power['namespace'],
-				'type' => $power['type'],
 				'name' => $power['name'],
 				'link' => $this->indexLinkPower($power)
 			];
@@ -90,7 +93,7 @@
 	 */
 	private function readmeModel(array &$classes): string
 	{
-		$this->sortClasses($classes, $this->defineTypeOrder());
+		$this->sortClasses($classes);
 
 		return $this->generateIndex($classes);
 	}
@@ -104,108 +107,34 @@
 	 */
 	private function generateIndex(array &$classes): string
 	{
-		$result = "# Index of powers\n";
+		$result = "# Index of Joomla! Powers\n";
-		$current_namespace = null;
 
 		foreach ($classes as $class)
 		{
-			if ($class['namespace'] !== $current_namespace)
-			{
-				$current_namespace = $class['namespace'];
-				$result .= "\n- **Namespace**: [{$current_namespace}](#" .
-					strtolower(str_replace('\\', '-', $current_namespace)) . ")\n";
-			}
-
 			// Add the class details
-			$result .= "\n  - " . $class['link'];
+			$result .= "\n - " . $class['link'];
 		}
 
-		return $result;
+		$result .= "\n> remember to replace the `---` with `___` in the JPK to activate that Joomla! Power in your code";
-	}
 
-	/**
+
-	 * Define the order of types for sorting purposes
+		return $result;
-	 *
-	 * @return array The order of types
-	 * @since 3.2.0
-	 */
-	private function defineTypeOrder(): array
-	{
-		return [
-			'interface' => 1,
-			'abstract' => 2,
-			'abstract class' => 2,
-			'final' => 3,
-			'final class' => 3,
-			'class' => 4,
-			'trait' => 5
-		];
 	}
 
 	/**
 	 * Sort the flattened array using a single sorting function
 	 *
 	 * @param array $classes The classes to sort
-	 * @param array $typeOrder The order of types
+	 *
 	 * @since 3.2.0
 	 */
-	private function sortClasses(array &$classes, array $typeOrder): void
+	private function sortClasses(array &$classes): void
 	{
-		usort($classes, function ($a, $b) use ($typeOrder) {
+		usort($classes, function ($a, $b) {
-			$namespaceDiff = $this->compareNamespace($a, $b);
-
-			if ($namespaceDiff !== 0)
-			{
-				return $namespaceDiff;
-			}
-
-			$typeDiff = $this->compareType($a, $b, $typeOrder);
-
-			if ($typeDiff !== 0)
-			{
-				return $typeDiff;
-			}
-
 			return $this->compareName($a, $b);
 		});
 	}
 
-	/**
-	 * Compare the namespace of two classes
-	 *
-	 * @param array $a First class
-	 * @param array $b Second class
-	 *
-	 * @return int Comparison result
-	 * @since 3.2.0
-	 */
-	private function compareNamespace(array $a, array $b): int
-	{
-		$namespaceDepthDiff = substr_count($a['namespace'], '\\') - substr_count($b['namespace'], '\\');
-
-		if ($namespaceDepthDiff === 0)
-		{
-			return strcmp($a['namespace'], $b['namespace']);
-		}
-
-		return $namespaceDepthDiff;
-	}
-
-	/**
-	 * Compare the type of two classes
-	 *
-	 * @param array $a First class
-	 * @param array $b Second class
-	 * @param array $typeOrder The order of types
-	 *
-	 * @return int Comparison result
-	 * @since 3.2.0
-	 */
-	private function compareType(array $a, array $b, array $typeOrder): int
-	{
-		return $typeOrder[$a['type']] <=> $typeOrder[$b['type']];
-	}
-
 	/**
 	 * Compare the name of two classes
 	 *
@@ -230,13 +159,11 @@
 	 */
 	private function indexLinkPower(array &$power): string
 	{
-		$type = $power['type'] ?? 'error';
 		$name = $power['name'] ?? 'error';
-		return '**' . $type . ' ' . $name . "** | "
+		return '**' . $name . "** | "
 			. $this->linkPowerRepo($power) . ' | '
-			. $this->linkPowerCode($power) . ' | '
+			. $this->linkPowerSettings($power) . ' | JPK: `'
-			. $this->linkPowerSettings($power) . ' | '
+			. $this->linkPowerJPK($power) .'`';
-			. $this->linkPowerSPK($power);
 	}
 
 	/**
@@ -253,20 +180,6 @@
 		return '[Details](' . $path . ')';
 	}
 
-	/**
-	 * Build the Link to the power settings in this repository
-	 *
-	 * @param array  $power  The power details.
-	 *
-	 * @return string
-	 * @since 3.2.0
-	 */
-	private function linkPowerCode(array &$power): string
-	{
-		$code = $power['code'] ?? 'error';
-		return '[Code](' . $code . ')';
-	}
-
 	/**
 	 * Build the Link to the power settings in this repository
 	 *
@@ -282,15 +195,15 @@
 	}
 
 	/**
-	 * Get the SuperPowerKey (SPK)
+	 * Get the JoomlaPowerKey (JPK)
 	 *
 	 * @param array  $power  The power details.
 	 *
 	 * @return string
 	 * @since 3.2.0
 	 */
-	private function linkPowerSPK(array &$power): string
+	private function linkPowerJPK(array &$power): string
 	{
-		$spk = $power['spk'] ?? 'error';
+		$jpk = $power['jpk'] ?? 'error';
-		return $spk;
+		return $jpk;
 	}

src/b836c1b1-b6b1-44f7-b8a2-9a763a4185b1/code.php

@@ -346,7 +346,7 @@ class Power implements PowerInterface
 		if ($this->isGuidValid($guid))
 		{
 			// now we search for it via the super power paths
-			if (empty($this->retry[$guid]) && $this->superpower->load($guid, ['remote', 'local']))
+			if (empty($this->retry[$guid]) && $this->superpower->item($guid, ['remote', 'local']))
 			{
 				// we found it and it was loaded into the database
 				unset($this->state[$guid]);

src/b836c1b1-b6b1-44f7-b8a2-9a763a4185b1/code.power

@@ -308,7 +308,7 @@
 		if ($this->isGuidValid($guid))
 		{
 			// now we search for it via the super power paths
-			if (empty($this->retry[$guid]) && $this->superpower->load($guid, ['remote', 'local']))
+			if (empty($this->retry[$guid]) && $this->superpower->item($guid, ['remote', 'local']))
 			{
 				// we found it and it was loaded into the database
 				unset($this->state[$guid]);