From 0f36deb141b3cf470d7db6602546248587e88936 Mon Sep 17 00:00:00 2001
From: "denise.soriano" <denise.soriano@hcl.com>
Date: Wed, 29 Jan 2025 00:07:58 +0800
Subject: [PATCH] Update README web components section

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index e5bb0e5..cccba44 100644
--- a/README.md
+++ b/README.md
@@ -31,26 +31,74 @@ Domino Rest Admin Client uses `npm` as its package manager. The `exec-maven-plug
 
 The config.json file contains the configurations for Admin UI and the paths that will be available in the WebJar.
 
-## Lit Web Components
-
-We are now using Lit 3.0 for web components. To build a custom Lit element, follow the following steps:
-
-1. Place your Lit element file in *src/components/lit-elements*.
-2. Add your Lit element's React counterpart in *src/components/lit-elements/LitElements.tsx* using the `createComponent` method.
-3. Import the created React component in the appropriate TSX, e.g. `import { LitAutocomplete } from '../lit-elements/LitElements'`.
+## 🌐 Lit Web Components
+
+We are now in the process of slowly migrating our current components to Lit 3.0 web components. To build a custom Lit element, please follow the following steps:
+
+1. Place your Lit element file in *src/components/lit-elements*. For example, we currently have Lit element with the tag name `lit-autocomplete`, under the class name `Autocomplete`.
+```javascript
+import { LitElement, html, css } from 'lit';
+
+class Autocomplete extends LitElement {
+    // definition of custom lit element goes here
+}
+
+customElements.define('lit-autocomplete', Autocomplete)
+
+export default Autocomplete
+```
+2. Add your Lit element's React counterpart in *src/components/lit-elements/LitElements.tsx* using the `createComponent` method (see [documentation](https://lit.dev/docs/frameworks/react/#createcomponent) for details). For example:
+```typescript
+export const LitAutocomplete = createComponent({
+  tagName: 'lit-autocomplete',
+  elementClass: Autocomplete,
+  react: React,
+});
+```
+3. From here, you will be able to import the Lit element in a component as another React component:
+```javascript
+import { LitAutocomplete } from '../lit-elements/LitElements'
+```
+
+### 🗝️ Accessing Values
+To access the Lit element's properties, create a reference using React's `useRef` hook and pass it onto the Lit element as a prop.
+
+```javascript
+const autocompleteRef = useRef<any>(null)
+<LitAutocomplete
+    ...options
+    ref={autocompleteRef}
+/>
+```
+
+The properties are accessible through the Lit element's shadow root.
+
+```javascript
+autocompleteRef.current.shadowRoot.querySelector('input')
+```
+
+### 👠 Shoelace
+
+As part of our move to web components, we are also using Shoelace, which is built under Lit, for more standard web components. Shoelace has an icon and an icon button; however, we couldn't use import the icons through reference, so we include them in the `IMG_DIR` (check config.dev).
+
+To use icons with Shoelace, add your icon SVG or PNG to the `IMG_DIR`, and reference that path in the `src` attribute of the Shoelace element. For example:
+```javascript
+<sl-icon src="${IMG_DIR}/shoelace/copy.svg"></sl-icon>
+```
+See the [Shoelace documentation](https://shoelace.style/components/icon/#custom-icons) for more details on custom icons.
 
 ## 🛠️ Building
 
 To build, run the following from the main project directory:
 
-Mac / linux
+### Mac / Linux
 
 `localbuild.sh`
 
-Windows
+### Windows
 
 `localbuild.cmd`
 
 ## License
 
-Copyright 2022-23, HCL America, Inc. under Apache License.
\ No newline at end of file
+Copyright 2022-25, HCL America, Inc. under Apache License.
\ No newline at end of file