AdoptedStyleSheets Update: Attach styles to document or this.shadowRoot

packages/controllers/adopted-stylesheets/README.md

@@ -2,19 +2,26 @@
 
 [![Latest version for outline-adopted-stylesheets-controller](https://img.shields.io/npm/v/@phase2/outline-adopted-stylesheets-controller)](https://www.npmjs.com/package/@phase2/outline-adopted-stylesheets-controller)
 
-> The `AdoptedStylesheets` controller is a part of the `@phase2/outline-adopted-stylesheets-controller` package.  This controller helps components attach "global" document styles without duplication at the component level as well as de-duping any previous inclusions into `AdoptedStylesheets`.
+> The `AdoptedStylesheets` controller is a part of the `@phase2/outline-adopted-stylesheets-controller` package. This controller assists components in attaching "global" document styles without duplication at the component level, as well as de-duping any previous inclusions into `AdoptedStylesheets`.
 
 ## Installing the `AdoptedStylesheets` Controller
 
-Install the new package:
+To install the new package, use the following command, specific to your package manager:
 
 ```bash
+# With Yarn
 yarn add @phase2/outline-adopted-stylesheets-controller
+
+# With NPM
+npm i --save-dev @phase2/outline-adopted-stylesheets-controller
+
+# With PNPM
+pnpm add --save-dev @phase2/outline-adopted-stylesheets-controller
 ```
 
 ## Overview
 
-Adopted stylesheets are a method to apply styles to a document or a shadow root. They are a part of the CSS Shadow Parts specification. Unfortunately, the original documentation link is no longer available. However, you can find more information about adopted stylesheets and their usage in web components in the following resources:
+Adopted stylesheets are a method to apply styles to a document or a shadow root. They are a part of the CSS Shadow Parts specification. For more information about adopted stylesheets and their usage in web components, refer to the following resources:
 
 - [MDN Web Docs: Document adoptedStyleSheets](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets): This documentation provides an in-depth look at the `adoptedStyleSheets` property of the `Document` interface.
 - [MDN Web Docs: ShadowRoot adoptedStyleSheets](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets): This documentation provides an in-depth look at the `adoptedStyleSheets` property of the `ShadowRoot` interface.
@@ -23,31 +30,64 @@ Adopted stylesheets are a method to apply styles to a document or a shadow root.
 
 The `AdoptedStylesheets` controller provides the following methods:
 
-- `constructor(globalStyles: CSSResult)`: This method is used to create a new instance of the `AdoptedStylesheets` controller. It takes a `CSSResult` object as a parameter, which represents the global styles to be adopted.
+- `constructor(globalStyles: CSSResult, root: Document | ShadowRoot)`: This method is used to create a new instance of the `AdoptedStylesheets` controller. It takes a `CSSResult` object and a root (either a `Document` or `ShadowRoot`) as parameters.
 
 - `hostConnected()`: This method is called when the host element is connected to the DOM. It adds the document's stylesheet to the adopted stylesheets if it is not already present.
 
 - `hostDisconnected()`: This method is called when the host element is disconnected from the DOM. It removes the document's stylesheet from the adopted stylesheets if it is present.
 
 ## Usage
 
-Here is an example of how to use the `AdoptedStylesheets` controller in a component:
+Here is an example of how to use the `AdoptedStylesheets` controller in a component. Samples will show incorporating two stylesheets, one to the `document` (global) and one to the `shadowRoot` (encapsulated). 
+
+### Importing the package
 
 ```typescript
 import { AdoptedStylesheets } from '@phase2/outline-adopted-stylesheets-controller';
-import { css, CSSResult } from 'lit';
-import { OutlineElement } from '@phase2/outline-core';
-import globalStyles from './my-component.lightDom.css.lit';
-
-class MyComponent extends OutlineElement {
-  AdoptedStylesheets: AdoptedStylesheets;
-
-  connectedCallback() {
-    super.connectedCallback();
-    this.AdoptedStylesheets = new AdoptedStylesheets(globalStyles);
-    this.addController(this.AdoptedStylesheets);
-  }
+```
+
+### Importing your stylesheet(s)
+
+```typescript
+import globalStyles from './styles/global-styles.css?inline';
+import encapsulatedStyles from './styles/encapsulated-styles.css?inline';
+```
+
+In the snippet above, you'll notice that we're importing stylesheets directly into our component using the `?inline` flag. This is a feature provided by modern bundlers like Vite and Webpack. The `?inline` flag tells the bundler to import the contents of the CSS file as a string, which can then be used directly in our JavaScript or TypeScript code.
+
+### Attaching a global stylesheet
+
+```typescript
+export class MyComponent extends LitElement {
+
+  GlobalStylesheets: AdoptedStylesheets | undefined = new AdoptedStylesheets(
+    this,
+    globalStyles,
+    document,
+  );
+
+  EncapsulatedStylesheets: AdoptedStylesheets | undefined;
+}
+```
+
+Above, the definition of `GlobalStylesheets` is calling the controller, and attaching immediately upon execution. Read on to understand why `EncapsulatedStylesheets` must be assigned differently.
+
+### Attaching an encapsulated stylesheet via `createRenderRoot`
+
+Because of the methods by which Adopted Stylesheets work, we must ensure that we have a `shadowRoot` prior to attaching styles to it. While this may seem overly verbose compared to using `static styles`, however, `static styles` is a Lit-ism, and then has us using the "Lit way" to attach our encapsulated styles, and "this way" to attach global ones. This consolidation is purposeful to ensure we are utilizing the same, modern, browser standards based methods when possible.
+
+```typescript
+createRenderRoot() {
+  const root = super.createRenderRoot();
+  this.EncapsulatedStylesheets = this.shadowRoot
+    ? new AdoptedStylesheets(this, encapsulatedStyles, this.shadowRoot)
+    : undefined;
+  return root;
 }
 ```
 
-In the provided example, the `connectedCallback` method is utilized. This method is invoked whenever the element is inserted into the DOM. Within this method, an instance of `AdoptedStylesheets` is created and added as a controller. This is a more efficient approach than creating the instance and adding the controller within the `constructor`. The reason for this is that it delays these operations until the element is actually inserted into the DOM. If there are many such elements that are created but not immediately added to the DOM, this approach can significantly improve the startup performance of your application. Therefore, the `connectedCallback` method is a crucial part of managing the lifecycle of a web component, especially when dealing with adopted stylesheets.
+The `createRenderRoot` method is used here for a very specific reason. In Lit, the `createRenderRoot` method is used to specify the container to which the template is rendered. By default, Lit renders the template into the component's Shadow DOM. This is done by returning `this.shadowRoot` in the `createRenderRoot` method, which is the default behavior.
+
+In this specific case, we are using `createRenderRoot` to adopt stylesheets into the shadow root of the component. This is done by creating a new instance of the `AdoptedStyleSheets` class and assigning it to `this.EncapsulatedStylesheets`. The `AdoptedStyleSheets` class is a controller that manages CSS stylesheets that are adopted into the document or a shadow root. By adopting the stylesheets into the shadow root, we ensure that the styles are scoped to this component and do not leak out to the rest of the page.
+
+This could not be achieved with other lifecycle methods in Lit. The `createRenderRoot` method is the only method that gives us direct access to the shadow root before the template is rendered, which is necessary for adopting the stylesheets. Other lifecycle methods like `connectedCallback`, `disconnectedCallback`, `updated`, `firstUpdated`, etc., are called at different stages of the component's lifecycle and do not give us the opportunity to adopt the stylesheets into the shadow root before the template is rendered.

packages/controllers/adopted-stylesheets/src/adopted-stylesheets.ts

@@ -1,33 +1,90 @@
-import { ReactiveController, CSSResult } from 'lit';
+import { ReactiveController, ReactiveControllerHost } from 'lit';
 
-export class AdoptedStyleSheets implements ReactiveController {
+/**
+ * `AdoptedStylesheets` is a class that implements the `ReactiveController` interface from the `lit` library.
+ * This class is used to manage CSS stylesheets that are adopted into the document or a shadow root.
+ *
+ * @property {CSSStyleSheet} adoptedSheet - The CSSStyleSheet object that is adopted into the document or a shadow root.
+ * @property {Document | ShadowRoot} root - The root where the stylesheet will be adopted.
+ */
+export class AdoptedStylesheets implements ReactiveController {
+  /**
+   * A static map that stores CSSStyleSheet objects by their CSS text.
+   * This allows for reuse of CSSStyleSheet objects across multiple instances of the class.
+   * @type {Map<string, CSSStyleSheet>}
+   */
   private static styleSheetMap = new Map<string, CSSStyleSheet>();
-  private documentSheet: CSSStyleSheet;
 
-  constructor(globalStyles: CSSResult) {
-    const cssText = globalStyles.cssText;
-    if (!AdoptedStyleSheets.styleSheetMap.has(cssText)) {
+  /**
+   * The CSSStyleSheet object that is adopted into the document or a shadow root.
+   * @type {CSSStyleSheet}
+   */
+  private adoptedSheet: CSSStyleSheet;
+
+  /**
+   * The root where the stylesheet will be adopted.
+   * This can be either the document or a shadow root.
+   * @type {Document | ShadowRoot}
+   */
+  private root: Document | ShadowRoot;
+
+  /**
+   * The host that this controller is associated with.
+   * @type {ReactiveControllerHost}
+   */
+  private host: ReactiveControllerHost;
+
+  /**
+   * The constructor for the `AdoptedStylesheets` class.
+   *
+   * @param {ReactiveControllerHost} host - The host that this controller is associated with.
+   * @param {string} cssText - A string that contains the CSS styles to be adopted.
+   * @param {Document | ShadowRoot} root - The root where the stylesheet will be adopted.
+   */
+  constructor(
+    host: ReactiveControllerHost,
+    cssText: string,
+    root: Document | ShadowRoot
+  ) {
+    this.host = host;
+    this.host.addController(this);
+    this.root = root;
+
+    if (!AdoptedStylesheets.styleSheetMap.has(cssText)) {
       const newSheet = new CSSStyleSheet();
-      newSheet.replaceSync(cssText);
-      AdoptedStyleSheets.styleSheetMap.set(cssText, newSheet);
+      newSheet.replace(cssText).catch(error => {
+        console.error('Failed to replace CSS text:', error);
+      });
+      AdoptedStylesheets.styleSheetMap.set(cssText, newSheet);
     }
-    this.documentSheet =
-      AdoptedStyleSheets.styleSheetMap.get(cssText) || new CSSStyleSheet();
+    this.adoptedSheet =
+      AdoptedStylesheets.styleSheetMap.get(cssText) || new CSSStyleSheet();
   }
 
+  /**
+   * The `hostConnected` method is called when the host element is connected to the DOM.
+   * This method adopts the CSSStyleSheet object into the root's adopted stylesheets if it's not already included.
+   */
   hostConnected() {
-    if (!document.adoptedStyleSheets.includes(this.documentSheet)) {
-      document.adoptedStyleSheets = [
-        ...document.adoptedStyleSheets,
-        this.documentSheet,
+    if (
+      this.root &&
+      !this.root.adoptedStyleSheets.includes(this.adoptedSheet)
+    ) {
+      this.root.adoptedStyleSheets = [
+        ...this.root.adoptedStyleSheets,
+        this.adoptedSheet,
       ];
     }
   }
 
+  /**
+   * The `hostDisconnected` method is called when the host element is disconnected from the DOM.
+   * This method removes the CSSStyleSheet object from the root's adopted stylesheets if it's included.
+   */
   hostDisconnected() {
-    if (document.adoptedStyleSheets.includes(this.documentSheet)) {
-      document.adoptedStyleSheets = document.adoptedStyleSheets.filter(
-        sheet => sheet !== this.documentSheet
+    if (this.root && this.root.adoptedStyleSheets.includes(this.adoptedSheet)) {
+      this.root.adoptedStyleSheets = this.root.adoptedStyleSheets.filter(
+        sheet => sheet !== this.adoptedSheet
       );
     }
   }