WebUI: Update code sharing doc with more detailed information

Change-Id: I8cf5f6fd6f13b9ea919ff95ff2a50ea45703d4b4
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5785055
Reviewed-by: John Lee <johntlee@chromium.org>
Commit-Queue: Rebekah Potter <rbpotter@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1341214}

docs/webui_code_sharing.md

@@ -64,7 +64,7 @@ therefore is narrowly shared:**
 *   UI code for viewing a PDF document (belongs in
     `chrome/browser/resources/pdf`)
 
-## **Step 2, for widely shared code: Determine which subfolder to use**
+## **How to add widely shared code**
 
 The organization of `ui/webui/resources` subfolders is as follows:
 
@@ -83,12 +83,94 @@ Used for more complex UI elements or components that are widely shared, but
 don’t fit the requirements for cr_elements. For more details see the
 [cr_components README](https://chromium.googlesource.com/chromium/src/+/main/ui/webui/resources/cr_components/README.md)
 
-## **Step 3, for widely shared code: Add unit testing**
+**Note: All widely shared code in `ui/webui/resources` should have unit tests
+at the time it is added to this folder**. Since the code is widely shared, it
+is likely many developers from different teams will need to make changes, and
+unit tests reduce the chance of such changes introducing regressions.
+Regressions in shared code are also more likely to be high impact, since they
+can impact many different UIs.
 
-**All widely shared code in `ui/webui/resources` should have unit tests at the
-time it is added to this folder**. Since the code is widely shared, it is likely
-many developers from different teams will need to make changes, and unit tests
-reduce the chance of such changes introducing regressions. Regressions in shared
-code are also more likely to be high impact, since they can impact many
-different UIs.
+## **How to add narrowly shared code**
 
+First, you will need to **create a folder for your narrowly shared code to
+reside in**. This folder should be a sibling of the highest level folder(s)
+that need to use it. Examples:
+
+*   `chrome/browser/resources/settings/` and
+    `chrome/browser/resources/password_manager/` share code in
+    `chrome/browser/resources/settings_shared/`.
+*   `chrome/browser/resources/side_panel/customize_chrome/` and
+    `chrome/browser/resources/side_panel/bookmarks/` share code in
+    `chrome/browser/resources/side_panel/shared`.
+
+Second, you need to **set up a `build_webui()` target in your new shared
+library folder**. This is largely the same as setting up a `build_webui()`
+target in any other folder, with some important possible differences below:
+
+*    `grd_resource_path_prefix` should be set to a path that you want all
+     UIs sharing the code to import these files from at runtime. For example,
+     the target in `settings_shared` sets this to `shared/settings`, and all
+     settings code importing these files imports them from
+     `/shared/settings/`.
+*    `ts_composite` must be set to true, because other library targets will
+     depend on the shared code.
+*    `webui_context_type` should be set based on all UIs using the code. In
+     particular, if both trusted and untrusted UIs will use the shared
+     library, this should be set to `relative` so that no absolute `chrome://`
+     or `chrome-untrusted://` paths are allowed (since such paths will not
+     work in both trusted and untrusted contexts).
+
+Third, **add dependencies and corresponding path mappings** in the build
+targets that depend on the new shared library. This is best demonstrated with
+an example:
+
+```
+build_webui("build_my_webui") {
+  grd_prefix = "my_webui"
+  # Other params here
+  ts_deps = [
+    "../foo_shared:build_ts",  # Limited shared library at ../foo_shared
+    "//ui/webui/resources/js:build_ts",
+  ]
+  # Map to the output directory of the `ts_library` build rule for
+  # chrome/browser/resources/foo_shared.
+  ts_path_mappings = [
+    "/foo_shared/*|" + rebase_path(
+        "$root_gen_dir/chrome/browser/resources/foo_shared/tsc/*",
+        target_gen_dir) ]
+  # other stuff goes here
+}
+```
+
+Fourth, **ensure that any UIs using the shared library will have access to the
+resources at runtime**. This has a few steps:
+*   Update `tools/gritsettings/resource_ids.spec` with an entry for the new
+    generated shared `.grd` file.
+*   Add a dependency on the shared library's generated `resources` target.
+    This should typically be added in the same target or group that depends
+    on the `resources` target(s) of the code relying on the library (often
+    in `chrome/browser/resources/BUILD.gn`).
+*   Add the generated `.pak` file in `chrome_paks.gni`.
+*   Register the shared library's resources in any data source that needs to
+    serve them at runtime (see example code below) using
+    `WebUIDataSource::AddResourcePaths()`.
+
+```cpp
+#include "chrome/grit/foo_shared_resources.h"
+#include "chrome/grit/bar_shared_resources.h"
+// ...
+HelloWorldUI::HelloWorldUI(content::WebUI* web_ui) {
+  // ...
+  // Add selected resources from foo_shared
+  static constexpr webui::ResourcePath kResources[] = {
+      {"foo_shared/foo_shared.css.js", IDR_FOO_SHARED_FOO_SHARED_CSS_JS},
+      {"foo_shared/foo_shared_vars.css.js",
+       IDR_FOO_SHARED_FOO_SHARED_VARS_CSS_JS},
+  };
+  source->AddResourcePaths(kResources);
+
+  // Add all shared resources from bar_shared
+  source->AddResourcePaths(
+      base::make_span(kBarSharedResources, kBarSharedResourcesSize));
+}
+```