@hotosm/ui 0.2.0-a9 → 0.2.0-b1

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 '../components/icons';
+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 '../components/icons';
+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 '../components/icons';
+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

package/components/icons.d.ts

@@ -0,0 +1,2 @@
+declare function registerBundledIcons(): void;
+export default registerBundledIcons;

package/components/icons.js

@@ -0,0 +1,72 @@
+//
+// Bundled icons hardcoded into hotosm/ui.
+// They are a subset of used Shoelace icons (which use Bootstrap icons)
+//
+import { registerIconLibrary } from '@shoelace-style/shoelace/dist/utilities/icon-library.js';
+const icons = {
+    list: `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-list" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M2.5 12a.5.5 0 0 1 .5-.5h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4a.5.5 0 0 1 .5-.5h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4a.5.5 0 0 1 .5-.5h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  `,
+    'info-circle': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle" viewBox="0 0 16 16">
+      <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
+      <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
+    </svg>
+  `,
+    'arrow-counterclockwise': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-arrow-counterclockwise" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M8 3a5 5 0 1 1-4.546 2.914.5.5 0 0 0-.908-.417A6 6 0 1 0 8 2v1z"/>
+      <path d="M8 4.466V.534a.25.25 0 0 0-.41-.192L5.23 2.308a.25.25 0 0 0 0 .384l2.36 1.966A.25.25 0 0 0 8 4.466z"/>
+    </svg>
+  `,
+    'arrow-clockwise': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-arrow-clockwise" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M8 3a5 5 0 1 0 4.546 2.914.5.5 0 0 1 .908-.417A6 6 0 1 1 8 2v1z"/>
+      <path d="M8 4.466V.534a.25.25 0 0 1 .41-.192l2.36 1.966c.12.1.12.284 0 .384L8.41 4.658A.25.25 0 0 1 8 4.466z"/>
+    </svg>
+  `,
+    'type-bold': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-type-bold" viewBox="0 0 16 16">
+      <path d="M8.21 13c2.106 0 3.412-1.087 3.412-2.823 0-1.306-.984-2.283-2.324-2.386v-.055a2.176 2.176 0 0 0 1.852-2.14c0-1.51-1.162-2.46-3.014-2.46H3.843V13H8.21zM5.908 4.674h1.696c.963 0 1.517.451 1.517 1.244 0 .834-.629 1.32-1.73 1.32H5.908V4.673zm0 6.788V8.598h1.73c1.217 0 1.88.492 1.88 1.415 0 .943-.643 1.449-1.832 1.449H5.907z"/>
+    </svg>
+  `,
+    'type-italic': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-type-italic" viewBox="0 0 16 16">
+      <path d="M7.991 11.674 9.53 4.455c.123-.595.246-.71 1.347-.807l.11-.52H7.211l-.11.52c1.06.096 1.128.212 1.005.807L6.57 11.674c-.123.595-.246.71-1.346.806l-.11.52h3.774l.11-.52c-1.06-.095-1.129-.211-1.006-.806z"/>
+    </svg>
+  `,
+    'type-underline': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-type-underline" viewBox="0 0 16 16">
+      <path d="M5.313 3.136h-1.23V9.54c0 2.105 1.47 3.623 3.917 3.623s3.917-1.518 3.917-3.623V3.136h-1.23v6.323c0 1.49-.978 2.57-2.687 2.57-1.709 0-2.687-1.08-2.687-2.57V3.136zM12.5 15h-9v-1h9v1z"/>
+    </svg>
+  `,
+    'justify-left': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-justify-left" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M2 12.5a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  `,
+    justify: `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-justify" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M2 12.5a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  `,
+    'justify-right': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-justify-right" viewBox="0 0 16 16">
+      <path fill-rule="evenodd" d="M6 12.5a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zm-4-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5zm0-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  `,
+};
+const libraryResolver = (name) => {
+    if (name in icons) {
+        return `data:image/svg+xml,${encodeURIComponent(icons[name])}`;
+    }
+    return '';
+};
+function registerBundledIcons() {
+    registerIconLibrary('bundled', {
+        resolver: libraryResolver,
+    });
+}
+export default registerBundledIcons;