@hotosm/ui 0.2.0-a9 → 0.2.0-b0

package/README.md

@@ -47,28 +47,33 @@ currently written in **Lit**, using TypeScript.
 
 ## Install
 
-### Via NPM
+There are two options for install:
+
+- **NPM**: appropriate for applications that have installable dependencies.
+- **CDN**: appropriate for HTML / Markdown / HTMX.
+
+### Components Bundle
+
+- This is the compiled JavaScript bundle generated from the TypeScript code.
+- The components require no additional dependencies and are minified.
+
+#### Via NPM
 
 - Install package `@hotosm/ui` as a dependency in your `package.json`.
-- Import the components and styles.
+- Import the components.
 
 ```html
 <script>
-  import '@hotosm/ui/dist/styles.css';
-  import Toolbar from '@hotosm/ui/dist/components.js';
+  import '@hotosm/ui/dist/components.js';
 </script>
 
 // Use the components in your templates
 <hot-button disabled> </hot-button>
 ```
 
-### Via CDN
+#### Via CDN
 
 ```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/styles.css"
-/>
 <script
   type="module"
   src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js"
@@ -77,4 +82,106 @@ currently written in **Lit**, using TypeScript.
 <hot-button disabled> </hot-button>
 ```
 
-See the docs for more [usage examples](https://hotosm.github.io/ui/usage/).
+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
+
+- 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": {
+        "@shoelace-style/shoelace": "^2.15.1"
+      }
+    ```
+
+    > Ideally the version of Shoelace installed should match the version used in
+    > hotosm/ui.
+
+- 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`.
+
+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.
+
+Use these instead of the standard `@hotosm/ui/components/xxx`:
+
+```bash
+pnpm install @hotosm/ui
+```
+
+```js
+import { Button } from '@hotosm/ui/react/Button'
+
+const HomePage = ({}) => {
+  return (
+    <div className="your-css-classes">
+      <div
+        ...
+      >
+        <Button disabled />
+      </div>
+    </div>
+  );
+};
+
+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 (particularly if using the ES Modules)
+
+To determine which version:
+
+- View the
+  [@hotosm/ui](https://www.npmjs.com/package/@hotosm/ui?activeTab=versions)
+  package on npmjs.com.
+- Select the version you are using.
+- Go to the `Code` tab, then open the `package.json` file.
+- The version of shoelace used should be in the `dependencies` section.
+
+If you are using a bundler, you must bundle the (icon) assets yourself,
+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