@hotosm/ui 0.2.0-b3 → 0.2.0-b5

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- markdownlint-disable -->
 <p align="center">
-  <img src="https://github.com/hotosm/fmtm/blob/main/images/hot_logo.png?raw=true" style="width: 200px;" alt="HOT"></a>
+  <img src="https://github.com/hotosm/ui/blob/main/theme/logo/hot-logo-png.png?raw=true" width="250" alt="HOT"></a>
 </p>
 <p align="center">
   <em>Shared Web Components with theming for use across HOTOSM tools.</em>
@@ -30,158 +30,158 @@
   </a>
 </p>
 
-📖 **Documentation**: <a href="https://hotosm.github.io/ui/" target="_blank">https://hotosm.github.io/ui/</a>
+<p align="center">
+  📖 <strong>Documentation</strong>: 
+  <a href="https://hotosm.github.io/ui/" target="_blank">https://hotosm.github.io/ui/</a><br>
+</p>
 
-🖥️ **Source Code**: <a href="https://github.com/hotosm/ui" target="_blank">https://github.com/hotosm/ui</a>
+<p align="center">
+  🖥️ <strong>Source Code</strong>: 
+  <a href="https://github.com/hotosm/ui" target="_blank">https://github.com/hotosm/ui</a><br>
+</p>
+
+<p align="center">
+  🎯 <strong>Roadmap / Tasks</strong>: 
+  <a href="https://github.com/orgs/hotosm/projects/37/views/3" target="_blank">https://github.com/orgs/hotosm/projects/37/views/3</a>
+</p>
 
----
 
 <!-- markdownlint-enable -->
 
-Shared UI components with theming for use across HOTOSM tools,
-to reduce code duplication.
+---
 
-The components are
-[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),
-currently written in **Lit**, using TypeScript.
+## Shared UI Components with HOT Theming
 
-## Install
+This repository contains HOT themed UI components to reduce code duplication
+and simplify the lives of developers needing to prototype and develop well
+designed web applications quickly.
 
-There are two options for install:
+They are available as
+[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
+with support for usage in [almost all](https://custom-elements-everywhere.com)
+modern web frameworks.
 
-- **NPM**: appropriate for applications that have installable dependencies.
-- **CDN**: appropriate for HTML / Markdown / HTMX.
+The main goal of this project is not to re-invent the wheel, or add an extra burden
+of development and maintenance.
 
-### Components Bundle
+## Quick start
 
-- This is the compiled JavaScript bundle generated from the TypeScript code.
-- The components require no additional dependencies and are minified.
+There are two options: NPM and Components Bundle.
+
+### NPM
+
+Appropriate for applications that have installable dependencies
 
-#### Via NPM
+`npm install @hotosm/ui`
 
-- Install package `@hotosm/ui` as a dependency in your `package.json`.
-- Import the components.
+Import the library in your project and use the components.
 
 ```html
 <script>
-  import '@hotosm/ui/dist/components.js';
+  import '@hotosm/ui/dist/style.css';
+  import '@hotosm/ui/dist/hotosm-ui.js';
 </script>
+```
 
-// Use the components in your templates
-<hot-button disabled> </hot-button>
+```html
+<hot-logo><hot-logo>
 ```
 
-#### Via CDN
+#### React
 
-```html
-<script
-  type="module"
-  src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js"
-></script>
+```js
+  import { Logo } from '@hotosm/ui/components/react';
+```
 
-<hot-button disabled> </hot-button>
+```jsx
+<Logo />
 ```
 
-The `jsdelivr` CDN only includes package releases, with `@latest` pointing to the
-most recent tagged release.
+### Components Bundle
 
-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`
+- This is the compiled JavaScript bundle generated from the TypeScript code.
+- The components require no additional dependencies and are minified.
 
-### ES Modules
+Appropriate for HTML / Markdown / HTMX.
 
-- 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`:
+```html
+<link
+  rel="stylesheet"
+  href="https://s3.amazonaws.com/hotosm-ui/latest/style.css"
+/>
 
-    ```json
-      "peerDependencies": {
-        "@shoelace-style/shoelace": "^2.15.1"
-      }
-    ```
+<script
+  type="module"
+  src="https://s3.amazonaws.com/hotosm-ui/latest/dist/hotosm-ui.js"
+></script>
 
-    > Ideally the version of Shoelace installed should match the version used in
-    > hotosm/ui.
+<hot-logo></hot-logo>
+```  
 
-- 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`.
+## Using Extra Shoelace Components
 
-Example:
+The HOT UI library contains many composite components, such as headers, sidebars,
+tracking banners, etc, and does not re-invent the wheel for low-level components.
 
-```js
-import '@hotosm/ui/components/Toolbar';
+Shoelace is an UI library that is exported directly from `@hotosm/ui`.
 
-// Then in your template
-<hot-button>Click Me</hot-button>
-```
+To access the low-level components, such as buttons, dropdowns, modals, etc,
+simply import the component of the same name from the [Shoelace docs]
+(<https://shoelace.style>):
 
-### React
+```js
+import '@hotosm/ui/components/button/button';
+```
 
-Versions of React below v19 require a specific 'wrapper' component to use the
-web components.
+```html
+<hot-button disabled variant="secondary">Can't Click Me</hot-button>
+```
 
-Use these instead of the standard `@hotosm/ui/components/xxx`:
+### React Shoelace Wrappers
 
-```bash
-pnpm install @hotosm/ui
+```js
+import { Button } from '@hotosm/ui/components';
 ```
 
-```js
-import { Button } from '@hotosm/ui/react/Button'
-
-const HomePage = ({}) => {
-  return (
-    <div className="your-css-classes">
-      <div
-        ...
-      >
-        <Button disabled />
-      </div>
-    </div>
-  );
-};
-
-export default HomePage;
+```html
+<Button disabled variant="secondary">Can't Click Me</Button>
 ```
 
-> Note that while web components must always have a closing tag, this is not
-> required for the React wrappers.
+### Examples
 
-## Using Extra Shoelace Components
+You can found examples for HTML and also all common frameworks
+(React, Svelte, Vue) under `/examples`.
 
-The UI library is not comprehensive & you may wish to use additional components
-from Shoelace in your app.
+### Development
 
-Ideally you should install the same version of @shoelace-style/shoelace as this
-library (particularly if using the ES Modules)
+HOT UI is developed in TypeScript, using Lit and @lit/react.
 
-To determine which version:
+Primarily we want to have:
 
-- 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.
+- Low level components exported from the Shoelace web component
+  library, simply re-exported with our default styling / CSS overrides.
+- A few composite components (header, sidebar, etc):
+  - Consistent styling across most of our tools where it counts.
+  - Reduction in duplicated logic, such as user management, OAuth login, etc.
+- Improved developer experience, reduced development time for new tools, while
+  maintaining consistency in look and feel of applications.
 
-If you are using a bundler, you must bundle the (icon) assets yourself,
-described in the Shoelace docs.
+### How to contribute
 
-### Example of bundling assets
+- Clone the project `git clone git@github.com:hotosm/ui.git`
+- Install dependencies `pnpm install`
+- Run the storybook `pnpm run dev`
+- Write code!
 
-- To include the Shoelace assets in your final bundle (dist), you could add
-  the following to your `package.json`:
+There's also a React storybook that you can use for testing:
 
-```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",
-  }
-```
+- Run the React storybook `pnpm run dev-react`
+
+For **styling**, check `/theme`:
+
+- `hot-sl.css` has a Shoelace theme, re-defining styles variables
+
+### License
 
-- Now the Shoelace assets will be bundled with your dist, under `/shoelace`.
-- Following the example, also add `public/assets/icons` to your `.gitignore` file.
+HOT UI is free and open source software! you may use any HOT UI project under the
+terms of the GNU Affero General Public License (AGPL) Version 3.

package/components/header/header.styles.ts

@@ -0,0 +1,103 @@
+import { css } from 'lit';
+import { cva } from "class-variance-authority";
+
+export const headerVariants = cva(
+  // Defaults to include in all variants
+  `
+      header
+  `,
+  {
+    variants: {
+      size: {
+          small: "header--size-small",
+          medium: "header--size-medium",
+          large: "header--size-large",
+      },
+      borderBottom: {
+          true: "border-bottom",
+      }
+    },
+  }
+);
+
+export type sizes = "small" | "medium" | "large";
+
+export const styles = css`
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 var(--sl-spacing-small);
+  }
+
+  .header.border-bottom {
+    border-bottom: var(--sl-spacing-3x-small) solid var(--sl-color-neutral-50);
+  }
+
+  .header--size-small {
+    height: var(--sl-spacing-4x-large);
+  }
+
+  .header--size-medium {
+    height: calc(var(--sl-spacing-4x-large) * 2);
+  }
+
+  .header--size-large {
+    height: calc(var(--sl-spacing-4x-large) * 4);
+  }
+
+  .header--link {
+    text-decoration: none;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--sl-spacing-small);
+  }
+
+  .header--title {
+    color: var(--sl-color-neutral-950);
+    font-family: var(--sl-font-sans);
+    font-size: var(--sl-font-size-x-large);
+  }
+
+  .header--tab-group {
+    flex-direction: column;
+  }
+
+  .header--tab::part(base) {
+    font-size: var(--sl-font-size-medium);
+    font-weight: var(--sl-font-weight-normal);
+    color: var(--sl-color-neutral-950);
+    padding: var(--sl-spacing-small) var(--sl-spacing-small);
+  }
+
+  .header--tab-group::part(base) {
+    --track-color: transparent;
+    --indicator-color: var(--sl-color-neutral-950);
+  }
+
+  .header--nav {
+    justify-content: space-between;
+    justify-items: center;
+    gap: var(--sl-spacing-medium);
+    font-weight: var(--sl-font-weight-semibold);
+  }
+
+  .header--nav-mobile {
+  }
+
+  .header--person-circle {
+    font-size: var(--sl-font-size-x-large);
+  }
+
+  .header--drawer {
+    font-size: var(--sl-font-size-x-large)
+  }
+
+  .header--right-section {
+  }
+
+  .header--logo-img {
+  }
+}
+`

package/components/header/header.ts

@@ -0,0 +1,160 @@
+import "../../theme/hot-sl.css";
+
+import "@shoelace-style/shoelace/dist/components/icon-button/icon-button.js";
+import "@shoelace-style/shoelace/dist/components/tab-panel/tab-panel.js";
+import "@shoelace-style/shoelace/dist/components/tab-group/tab-group.js";
+import "@shoelace-style/shoelace/dist/components/tab/tab.js";
+
+import { LitElement, html } from "lit";
+import { property } from "lit/decorators.js";
+import { headerVariants, type sizes, styles } from './header.styles.js';
+import type { CSSResultGroup } from 'lit';
+
+import registerBundledIcons from "../../components/icons";
+
+registerBundledIcons();
+
+interface MenuItem {
+  label: string;
+  clickEvent: () => void;
+}
+
+export class Header extends LitElement {
+
+  static styles: CSSResultGroup = [styles];
+
+  name = "hot-header";
+
+  /** Use a text-based title in the header. */
+  @property({ type: String })
+  accessor title: string = "";
+
+  /** Display a logo on the left of the header. */
+  @property({ type: String })
+  accessor logo: string | URL = "";
+
+  /** Add a drawer icon with a click event to e.g. open a sidebar. */
+  @property({ type: Boolean })
+  accessor drawer: boolean = true;
+
+  /** Array of menu items to include as navigation tabs. */
+  @property({ type: Array })
+  accessor tabs: MenuItem[] = [];
+
+  /** Size of toolbar vertically. */
+  @property({ type: String })
+  accessor size: sizes = "small";
+
+  /** Border bottom. */
+  @property({ type: Boolean })
+  accessor borderBottom: boolean = true;
+  
+  @property()
+  accessor selectedTab: number = 0;
+
+  protected render() {
+    const logoSrc =
+      typeof this.logo === "string" || this.logo instanceof URL
+        ? typeof this.logo === "string"
+          ? this.logo
+          : this.logo.href
+        : "";
+
+    return html`
+      <header class=${headerVariants({ 
+          size: this.size,
+          borderBottom: this.borderBottom
+        })}>
+        <a href="/" class="header--link">
+          ${logoSrc.length > 0
+            ? html`
+                <img
+                  id="logo"
+                  src="${this.logo}"
+                  alt="Logo"
+                  class="header--logo-img"
+                />
+              `
+            : html`
+            <hot-logo
+              ?iconOnly="${this.title.length > 0}"
+            >
+            </hot-logo>
+            `}
+          ${this.title.length > 0
+            ? html`
+                <h1 class="header--title">
+                  ${this.title}
+                </h1>
+              `
+            : null}
+        </a>
+
+        ${/* Navigation bar for desktop, hide on mobile */ ""}
+        <nav
+          class="header--nav"
+        >
+          <sl-tab-group class="header--tab-group">
+            ${this.tabs.map(
+              (item, index) => html`
+                <sl-tab
+                  class="header--tab"
+                  slot="nav"
+                  panel="general"
+                  @click=${(e: MouseEvent) => {
+                    this._selectTab(e, item.clickEvent, index);
+                  }}
+                  ?selected=${this.selectedTab === index}
+                  >${item.label}</sl-tab
+                >
+              `
+            )}
+          </sl-tab-group>
+        </nav>
+
+        ${/* Stacked navigation drawer for mobile */ ""}
+        ${/* NOTE this should probably be in a drawer instead */ ""}
+        <nav
+          class="header--nav-mobile"
+        ></nav>
+
+        <div id="right-section" class="header--right-section">
+          <sl-icon-button
+            library="bundled"
+            name="person-circle"
+            class="header--person-circle"
+            label="login"
+            @click=${(e: MouseEvent) => {
+              this._handleLogin(e);
+            }}
+          ></sl-icon-button>
+            ${this.drawer
+              ? html`
+                  <sl-icon-button
+                    library="bundled"
+                    class="header--drawer"
+                    name="list"
+                    label="drawer-open"
+                  ></sl-icon-button>
+                `
+              : null}
+          </div>
+        </div>
+      </header>
+    `;
+  }
+
+  private _selectTab(_e: MouseEvent, clickAction: () => void, index: number) {
+    this.selectedTab = index;
+    clickAction();
+  }
+
+  private _handleLogin(_e: MouseEvent) {
+    this.dispatchEvent(new Event("login"));
+  }
+}
+
+export default Header;
+
+// Define web component
+customElements.define("hot-header", Header);

package/components/{icons.js → icons.ts}

@@ -2,71 +2,83 @@
 // Bundled icons hardcoded into hotosm/ui.
 // They are a subset of used Shoelace icons (which use Bootstrap icons)
 //
+
+import type { IconLibraryResolver } from "@shoelace-style/shoelace/dist/components/icon/library";
 import { registerIconLibrary } from '@shoelace-style/shoelace/dist/utilities/icon-library.js';
+
 const icons = {
-    list: `
+  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': `
+  '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': `
+  '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': `
+  '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': `
+  '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': `
+  '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': `
+  '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': `
+  '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: `
+  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': `
+  '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>
   `,
+  'person-circle': `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-person-circle" viewBox="0 0 16 16">
+      <path d="M11 6a3 3 0 1 1-6 0 3 3 0 0 1 6 0z"/>
+      <path fill-rule="evenodd" d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8zm8-7a7 7 0 0 0-5.468 11.37C3.242 11.226 4.805 10 8 10s4.757 1.225 5.468 2.37A7 7 0 0 0 8 1z"/>
+    </svg>
+  `
 };
-const libraryResolver = (name) => {
+
+const libraryResolver: IconLibraryResolver = (name: string) => {
     if (name in icons) {
-        return `data:image/svg+xml,${encodeURIComponent(icons[name])}`;
+        return `data:image/svg+xml,${encodeURIComponent(icons[name as keyof typeof icons])}`;
     }
     return '';
-};
+}
+
 function registerBundledIcons() {
     registerIconLibrary('bundled', {
         resolver: libraryResolver,
     });
 }
+
 export default registerBundledIcons;