From b75fe336944b39c03cabcf9cdbcdc8893de17c9a Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 16 May 2023 00:53:46 -0700
Subject: [PATCH] (NFC) Cross-reference Civi/Esm/README.md

---
 Civi/Esm/BrowserLoader.php |  3 +++
 Civi/Esm/ImportMap.php     | 21 +++++----------------
 Civi/Esm/ShimLoader.php    |  5 +++++
 3 files changed, 13 insertions(+), 16 deletions(-)

diff --git a/Civi/Esm/BrowserLoader.php b/Civi/Esm/BrowserLoader.php
index 4964b1e285..5529071a4c 100644
--- a/Civi/Esm/BrowserLoader.php
+++ b/Civi/Esm/BrowserLoader.php
@@ -21,6 +21,9 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  * This should be the simplest and most efficient way to load modules. However, there may be
  * compatibility issues with older browsers or future UFs.
  *
+ * For a fuller description of this mechanism, see the neighboring README.
+ * @see ./README.md
+ *
  * @service esm.loader.browser
  */
 class BrowserLoader extends \Civi\Core\Service\AutoService implements EventSubscriberInterface {
diff --git a/Civi/Esm/ImportMap.php b/Civi/Esm/ImportMap.php
index b4d851b54e..d74856f471 100644
--- a/Civi/Esm/ImportMap.php
+++ b/Civi/Esm/ImportMap.php
@@ -11,25 +11,14 @@ use Civi\Core\HookInterface;
  * - import { TableWidget } from 'https://example.com/sites/all/modules/civicrm/js/table-widget.js';
  * - import { TableWidget } from 'civicrm/js/tab-widget.js';
  *
- * The logical-path (`civicrm/js/tab-widget.js`) is much easier to read, and it adapts
- * better to more environments.
+ * The purpose of `Civi\Esm\ImportMap` (aka `esm.import_map`) is to build a list of all
+ * the logical prefixes supported by `civicrm-core` and CiviCRM extensions.
  *
- * Logical-paths must be defined with an import-map:
- *
- *   <script type="importmap">
- *   { "import": {"civicrm/": "https://example.com/sites/all/modules/civicrm"}}
- *   </script>
- *
- * If your extension includes ESM files, then you may want to add items to the import-map:
- *
- *   function myext_civicrm_esmImportMap(array &$importMap, array $context): void {
- *     $importMap['imports']['foo/'] = E::url('js/foo/');
- *     $importMap['imports']['bar/'] = E::url('packages/bar/dist/');
- *   }
- *
- * Note: These mappings are used by an ESM Loader, such as "BasicLoader".
+ * This is generally consumed by BrowserLoader or a similar class. For a fuller description
+ * of this mechanism, see the neighboring README.
  *
  * @see \Civi\Esm\BrowserLoader
+ * @see ./README.md
  *
  * @service esm.import_map
  */
diff --git a/Civi/Esm/ShimLoader.php b/Civi/Esm/ShimLoader.php
index 49393e90d1..5ef6d04a82 100644
--- a/Civi/Esm/ShimLoader.php
+++ b/Civi/Esm/ShimLoader.php
@@ -26,6 +26,11 @@ use Civi;
  * support. This ensures consistent functionality on all browsers, but it also makes the overhead
  * mandatory.
  *
+ * For a fuller description of this mechanism, see the neighboring README.
+ *
+ * @see \Civi\Esm\BrowserLoader
+ * @see ./README.md
+ *
  * @service esm.loader.shim
  */
 class ShimLoader extends BrowserLoader {
-- 
2.25.1