Skip to content

Commit

Permalink
Merge pull request #313 from HCL-TECH-SOFTWARE/task/MXOP-12758-web-co…
Browse files Browse the repository at this point in the history
…mponents-readme

Update README web components section
  • Loading branch information
rwilkins108 authored Jan 28, 2025
2 parents fd9f05d + 0f36deb commit 65b821f
Showing 1 changed file with 58 additions and 10 deletions.
68 changes: 58 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copyright 2022-25, HCL America, Inc. under Apache License.

0 comments on commit 65b821f

Please sign in to comment.