@hotosm/ui 0.2.0-b4 → 0.2.0-b6

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,166 +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
 
-Compositie components (header, sidebar, etc) are generated using Shoelace, with
-the remaining low-level components exported from the Shoelace library too.
+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.
 
-## 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.
 
-There are two options for install:
+The main goal of this project is not to re-invent the wheel, or add an extra burden
+of development and maintenance.
 
-- **NPM**: appropriate for applications that have installable dependencies.
-- **CDN**: appropriate for HTML / Markdown / HTMX.
+## Quick start
 
-### Components Bundle
+There are two options: NPM and Components Bundle.
 
-- This is the compiled JavaScript bundle generated from the TypeScript code.
-- The components require no additional dependencies and are minified.
+### 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/style.css';
-  import '@hotosm/ui/dist/components.js';
+  import '@hotosm/ui/dist/hotosm-ui.js';
 </script>
+```
 
-// Use the components in your templates
-<hot-header @login="someFunction()"> </hot-header>
+```html
+<hot-logo><hot-logo>
+```
+
+#### React
+
+```js
+  import { Logo } from '@hotosm/ui/components/react';
+```
+
+```jsx
+<Logo />
 ```
 
-#### Via CDN
+### Components Bundle
+
+- This is the compiled JavaScript bundle generated from the TypeScript code.
+- The components require no additional dependencies and are minified.
+
+Appropriate for HTML / Markdown / HTMX.
 
 ```html
-// Import the styles (or create your own)
 <link
   rel="stylesheet"
-  href="https://s3.amazonaws.com/hotosm-ui/latest/style.css"
+  href="https://s3.amazonaws.com/hotosm-ui/latest/dist/style.css"
 />
 
-// Import the components
 <script
   type="module"
-  src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js"
+  src="https://s3.amazonaws.com/hotosm-ui/latest/dist/hotosm-ui.js"
 ></script>
 
-<hot-header @login="someFunction()> </hot-header>
-```
-
-The `jsdelivr` CDN only includes package releases, with `@latest` pointing to the
-most recent tagged release.
+<hot-logo></hot-logo>
+```  
 
-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 Lit as a `peerDependency` in your `package.json`:
+## Using Extra Shoelace Components
 
-    ```json
-      "peerDependencies": {
-        "lit": "^3.1.0"
-      }
-    ```
+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.
 
-    > Ideally the version of Lit installed should match the version used in
-    > hotosm/ui.
+Shoelace is an UI library that is exported directly from `@hotosm/ui`.
 
-Example:
+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>):
 
 ```js
-import '@hotosm/ui/components/header/header';
-
-// Then in your template
-<hot-header @login="${someFunction()}"></hot-header>
+import '@hotosm/ui/components/button/button';
 ```
 
-### React
-
-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/Header'
-
-const HomePage = ({}) => {
-  return (
-    <div className="your-css-classes">
-      <div
-        ...
-      >
-        <Header @onLogin="${someFunction()}" />
-      </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 contains many composite components, such as headers, sidebars,
-tracking banners, etc, and does not re-invent the wheel for low-level components.
+### Development
 
-Shoelace is an excellent UI library that is exported directly from `@hotosm/ui`.
+HOT UI is developed in TypeScript, using Lit and @lit/react.
 
-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>):
+Primarily we want to have:
 
-```js
-import '@hotosm/ui/components/button/button';
+- 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.
 
-// Then in your template
-<hot-button disabled variant="secondary">Can't Click Me</hot-button>
-```
+### How to contribute
 
-If you are using a bundler, you must bundle the (icon) assets yourself,
-described in the Shoelace docs.
+- Clone the project `git clone git@github.com:hotosm/ui.git`
+- Install dependencies `pnpm install`
+- Run the storybook `pnpm run dev`
+- Write code!
 
-### Example of bundling assets
+There's also a React storybook that you can use for testing:
 
-- To include the Shoelace assets in your final bundle (dist), you could add
-  the following to your `package.json`:
+- Run the React storybook `pnpm run dev-react`
 
-```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",
-  }
-```
+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 {
+  }
+}
+`