@hotosm/ui 0.2.0-a8 → 0.2.0-b0

package/README.md

@@ -47,95 +47,54 @@ currently written in **Lit**, using TypeScript.
 
 ## Install
 
-Via NPM:
+There are two options for install:
 
-```bash
-npm install @hotosm/ui
+- **NPM**: appropriate for applications that have installable dependencies.
+- **CDN**: appropriate for HTML / Markdown / HTMX.
 
-yarn add @hotosm/ui
+### Components Bundle
 
-pnpm install @hotosm/ui
-```
+- This is the compiled JavaScript bundle generated from the TypeScript code.
+- The components require no additional dependencies and are minified.
 
-## Usage
+#### Via NPM
 
-### CDN (HTML / HTMX)
+- Install package `@hotosm/ui` as a dependency in your `package.json`.
+- Import the components.
 
 ```html
-// Import Shoelace dependency
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style
-  /shoelace@2.15.1/cdn/themes/light.css" />
-<script
-  type="module"
-  src="https://cdn.jsdelivr.net/npm/@shoelace-style/
-  shoelace@2.15.1/cdn/shoelace-autoloader.js"
-></script>
-
-// Import the components & styles (or add your own styling)
-<link
-  rel="stylesheet"
-  href="https://s3.amazonaws.com/hotosm-ui/latest/theme/styles.css"
-/>
-<script
-  type="module"
-  src="https://s3.amazonaws.com/hotosm-ui/latest/components/Button.js"
-></script>
-
-<div>
-  <hot-button disabled> </hot-button>
-</div>
-```
-
-> Using the Shoelace autoloader will lazy load only the components you use.
-
-See the docs for more [usage examples](https://hotosm.github.io/ui/usage/).
-
-> Components are versioned under subdirectories, with /latest/ tracking the
-> `main` branch, plus versioned releases.
-
-### ES6 Imports (most frameworks)
-
-Install your required version with a pin, or latest:
-
-```bash
-pnpm install @hotosm/ui
-```
-
-```js
 <script>
-  import '@hotosm/ui/theme/styles.css'
-  import '@hotosm/ui/components/Button'
+  import '@hotosm/ui/dist/components.js';
 </script>
 
-<hot-button disabled></hot-button>
+// Use the components in your templates
+<hot-button disabled> </hot-button>
 ```
 
-> Note that web components must always have a closing tag.
-
-#### Importing Icons
-
-The icon pack for Shoelace must be imported to display in components.
-
-There are two options:
-
-##### 1. CDN Assets
-
-Just add the Shoelace icons via CDN in your HTML file:
+#### Via CDN
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style
-/shoelace@2.15.1/cdn/themes/light.css" />
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js"
+></script>
 
-// Or dark
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style
-/shoelace@2.15.1/cdn/themes/dark.css" />
+<hot-button disabled> </hot-button>
 ```
 
-##### 2. Bundle Assets Yourself
+The `jsdelivr` CDN only includes package releases, with `@latest` pointing to the
+most recent tagged release.
+
+There is also an S3-based CDN, where `latest` tracks the `main` branch of the repo:
+  `https://s3.amazonaws.com/hotosm-ui/latest/dist/components.js`
+
+### ES Modules
 
-- Add Shoelace as a `peerDependency` and to your `package.json`:
+- Using the TypeScript ES Modules allows for cherry-picking components, so
+'tree-shaking' can remove the remaining ones you don't use.
+- If you are developing an application that uses `@hotosm/ui` components,
+including a bundler such as rollup/vite/webpack, this is probably the best approach.
+- However, you must first add Shoelace as a `peerDependency` in your `package.json`:
 
     ```json
       "peerDependencies": {
@@ -143,29 +102,23 @@ Just add the Shoelace icons via CDN in your HTML file:
       }
     ```
 
-- Also add `vite-plugin-static-copy` as a devDependency:
-    `pnpm install -D vite-plugin-static-copy`
-- Add to your `vite.config.ts`:
-
-    ```js
-    import { viteStaticCopy } from 'vite-plugin-static-copy';
-
-    export default defineConfig({
-      plugins: [
-        viteStaticCopy({
-          targets: [
-            {
-            src: 'node_modules/@shoelace-style/shoelace/dist/assets',
-            dest: ''
-            }
-          ]
-        }),
-      ],
-    ```
+    > Ideally the version of Shoelace installed should match the version used in
+    > hotosm/ui.
 
-- Now the Shoelace assets will be bundled with your dist, under `/shoelace`.
+- This will also install subdependencies such as Lit.
+- If there is a conflict between Lit versions, the `lit` package can also be pinned
+  via `peerDependency`.
 
-#### React
+Example:
+
+```js
+import '@hotosm/ui/components/Toolbar';
+
+// Then in your template
+<hot-button>Click Me</hot-button>
+```
+
+### React
 
 Versions of React below v19 require a specific 'wrapper' component to use the
 web components.
@@ -194,13 +147,16 @@ const HomePage = ({}) => {
 export default HomePage;
 ```
 
+> Note that while web components must always have a closing tag, this is not
+> required for the React wrappers.
+
 ## Using Extra Shoelace Components
 
 The UI library is not comprehensive & you may wish to use additional components
 from Shoelace in your app.
 
 Ideally you should install the same version of @shoelace-style/shoelace as this
-library.
+library (particularly if using the ES Modules)
 
 To determine which version:
 
@@ -212,4 +168,20 @@ To determine which version:
 - The version of shoelace used should be in the `dependencies` section.
 
 If you are using a bundler, you must bundle the (icon) assets yourself,
-as described above.
+described in the Shoelace docs.
+
+### Example of bundling assets
+
+- To include the Shoelace assets in your final bundle (dist), you could add
+  the following to your `package.json`:
+
+```json
+  "scripts": {
+    "clean-icons": "rm -rf public/assets/icons",
+    "get-icons": "cp -r node_modules/@shoelace-style/shoelace/dist/assets/icons public/",
+    "setup-dist": "pnpm run clean-icons && pnpm run get-icons",
+  }
+```
+
+- Now the Shoelace assets will be bundled with your dist, under `/shoelace`.
+- Following the example, also add `public/assets/icons` to your `.gitignore` file.

package/components/Header.js

@@ -12,6 +12,8 @@ import '@shoelace-style/shoelace/dist/components/tab-panel/tab-panel.js';
 import '@shoelace-style/shoelace/dist/components/tab/tab.js';
 import { LitElement, css, html } from "lit";
 import { property } from "lit/decorators.js";
+import registerBundledIcons from '../theme/icons/bundled';
+registerBundledIcons();
 const hotLogo = new URL('../theme/logo.png', import.meta.url);
 // import { cva } from "class-variance-authority";
 // const headerStyle = cva(
@@ -58,7 +60,7 @@ export class Header extends LitElement {
 
       ${this.drawer ? html `
         <div id="drawer-block" style="font-size: 32px;">
-          <sl-icon-button name="list" label="drawer-open"></sl-icon-button>
+          <sl-icon-button library="bundled" name="list" label="drawer-open"></sl-icon-button>
         </div>
       ` : null}
 

package/components/Toolbar.js

@@ -13,6 +13,8 @@ import '@shoelace-style/shoelace/dist/components/icon/icon.js';
 import '@shoelace-style/shoelace/dist/components/tooltip/tooltip.js';
 import { LitElement, css, html } from "lit";
 import { property } from "lit/decorators.js";
+import registerBundledIcons from '../theme/icons/bundled';
+registerBundledIcons();
 // import { cva } from "class-variance-authority";
 // const toolbarStyle = cva(
 //   "some-css-var",
@@ -99,7 +101,7 @@ export class Toolbar extends LitElement {
     renderButton({ content, icon, label, action }) {
         return html `
       <sl-tooltip content=${content} placement="${this.tooltipPosition}">
-        <sl-button @click=${action ?? (() => { })}><sl-icon name=${icon} label=${label}></sl-icon></sl-button>
+        <sl-button @click=${action ?? (() => { })}><sl-icon library="bundled" name=${icon} label=${label}></sl-icon></sl-button>
       </sl-tooltip>
     `;
     }

package/components/Tracking.js

@@ -10,6 +10,8 @@ import '@shoelace-style/shoelace/dist/themes/dark.css';
 import '@shoelace-style/shoelace/dist/components/alert/alert.js';
 import { LitElement, css, html } from "lit";
 import { property, state } from "lit/decorators.js";
+import registerBundledIcons from '../theme/icons/bundled';
+registerBundledIcons();
 export class Tracking extends LitElement {
     constructor() {
         super(...arguments);
@@ -25,7 +27,7 @@ export class Tracking extends LitElement {
       variant="danger"
       ?open=${this.isOpen}
     >
-    <sl-icon id="hot-red-text" slot="icon" name="info-circle"></sl-icon>
+    <sl-icon id="hot-red-text" library="bundled" slot="icon" name="info-circle"></sl-icon>
 
     <p id="tracking-header">
     About the information we collect