-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
95 additions
and
142 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,96 +1,80 @@ | ||
| # HOT Shared UI | ||
|
|
||
| <!-- 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> | ||
| </p> | ||
| <p align="center"> | ||
| <em>Shared Web Components with theming for use across HOTOSM tools.</em> | ||
| </p> | ||
| <p align="center"> | ||
| <a href="https://github.com/hotosm/ui/actions/workflows/publish.yml" target="_blank"> | ||
| <img src="https://github.com/hotosm/ui/actions/workflows/publish.yml/badge.svg?event=release" alt="Publish"> | ||
| </a> | ||
| <a href="https://github.com/hotosm/ui/actions/workflows/cdn_deploy.yml" target="_blank"> | ||
| <img src="https://github.com/hotosm/ui/actions/workflows/cdn_deploy.yml/badge.svg?branch=main" alt="CDN Deploy"> | ||
| </a> | ||
| <a href="https://github.com/hotosm/ui/actions/workflows/docs.yml" target="_blank"> | ||
| <img src="https://github.com/hotosm/ui/actions/workflows/docs.yml/badge.svg" alt="Publish Docs"> | ||
| </a> | ||
| <a href="https://www.npmjs.com/package/@hotosm/ui" target="_blank"> | ||
| <img src="https://img.shields.io/npm/v/%40hotosm/ui?color=334D058" | ||
| alt="Package version"> | ||
| </a> | ||
| <a href="https://npmtrends.com/@hotosm/ui" target="_blank"> | ||
| <img src="https://img.shields.io/npm/dm/%40hotosm%2Fui" | ||
| alt="Downloads"> | ||
| </a> | ||
| <a href="https://github.com/hotosm/ui/blob/main/LICENSE.md" target="_blank"> | ||
| <img src="https://img.shields.io/github/license/hotosm/ui.svg" alt="License"> | ||
| </a> | ||
| </p> | ||
| # HOT UI | ||
|
|
||
| 📖 **Documentation**: <a href="https://hotosm.github.io/ui/" target="_blank">https://hotosm.github.io/ui/</a> | ||
| ## Shared UI components with HOT theming. | ||
|
|
||
| 🖥️ **Source Code**: <a href="https://github.com/hotosm/ui" target="_blank">https://github.com/hotosm/ui</a> | ||
| HOT themed UI components to reduce code duplication and make live easier for developers, available as [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) and React components. | ||
|
|
||
| 🎯 **Roadmap / Tasks**: <a href="https://github.com/orgs/hotosm/projects/37/views/3" target="_blank">https://github.com/orgs/hotosm/projects/37/views/3</a> | ||
| The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance. | ||
|
|
||
| --- | ||
| <img src="https://github.com/hotosm/ui/blob/main/theme/logo/hot-logo-png.png" width="150"> | ||
|
|
||
| <!-- markdownlint-enable --> | ||
| [](https://github.com/hotosm/ui/actions/workflows/publish.yml/) | ||
| [](https://github.com/hotosm/ui/actions/workflows/cdn_deploy.yml) | ||
| [](https://github.com/hotosm/ui/actions/workflows/docs.yml) | ||
| [](https://www.npmjs.com/package/@hotosm/ui) | ||
| [](https://npmtrends.com/@hotosm/ui) | ||
| [](https://github.com/hotosm/ui/blob/main/LICENSE.md) | ||
|
|
||
| Shared UI components with theming for use across HOTOSM tools, | ||
| to reduce code duplication. | ||
| 📖 **Documentation**: <a href="https://hotosm.github.io/ui/" target="_blank">https://hotosm.github.io/ui/</a> | ||
|
|
||
| The components are | ||
| [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), | ||
| currently written in **Lit**, using TypeScript. | ||
| 🖥️ **Source Code**: <a href="https://github.com/hotosm/ui" target="_blank">https://github.com/hotosm/ui</a> | ||
|
|
||
| The main goal of this project is not to re-invent the wheel, or add an extra | ||
| burden of development and maintenance. | ||
| 🎯 **Roadmap / Tasks**: <a href="https://github.com/orgs/hotosm/projects/37/views/3" target="_blank">https://github.com/orgs/hotosm/projects/37/views/3</a> | ||
|
|
||
| Primarily we want to have: | ||
| --- | ||
|
|
||
| - Low level components exported from the excellent 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. | ||
|
|
||
| ## Install | ||
|
|
||
| There are two options for install: | ||
|
|
||
| - **NPM**: appropriate for applications that have installable dependencies. | ||
| - **CDN**: appropriate for HTML / Markdown / HTMX. | ||
| - **Components Bundle**: appropriate for HTML / Markdown / HTMX. | ||
|
|
||
| ### Components Bundle | ||
| ### NPM | ||
|
|
||
| - This is the compiled JavaScript bundle generated from the TypeScript code. | ||
| - The components require no additional dependencies and are minified. | ||
| #### Install | ||
|
|
||
| #### Via NPM | ||
| `npm install @hotosm/ui` | ||
|
|
||
| - Install package `@hotosm/ui` as a dependency in your `package.json`. | ||
| - Import the components. | ||
| #### Web Components | ||
|
|
||
| Include the code in your project: | ||
|
|
||
| ```html | ||
| <script> | ||
| import '@hotosm/ui/dist/style.css'; | ||
| import '@hotosm/ui/dist/components.js'; | ||
| import '@hotosm/ui/dist/hotosm-ui.js'; | ||
| </script> | ||
| ``` | ||
|
|
||
| Or: | ||
|
|
||
| ```js | ||
| import { Button } from '@hotosm/ui/components'; | ||
| ``` | ||
|
|
||
| And use the components: | ||
|
|
||
| ```html | ||
| <hot-button @onClick="someFunction()">Click me!</button> | ||
| ``` | ||
|
|
||
| Or: | ||
|
|
||
| // Use the components in your templates | ||
| <hot-header @login="someFunction()"> </hot-header> | ||
| ```html | ||
| <Button onClick="someFunction()">Click me!</Button> | ||
| ``` | ||
|
|
||
| ### Components Bundle | ||
|
|
||
| - This is the compiled JavaScript bundle generated from the TypeScript code. | ||
| - The components require no additional dependencies and are minified. | ||
|
|
||
| #### Via CDN | ||
|
|
||
| ```html | ||
| // Import the styles (or create your own) | ||
| // Import the styles | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://s3.amazonaws.com/hotosm-ui/latest/style.css" | ||
|
|
@@ -99,109 +83,78 @@ There are two options for install: | |
| // 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/components.js" | ||
| ></script> | ||
|
|
||
| <hot-header @login="someFunction()> </hot-header> | ||
| ``` | ||
| <hot-button @onClick="someFunction()> </hot-button> | ||
| ``` | ||
| ## Using Extra Shoelace Components | ||
| The `jsdelivr` CDN only includes package releases, with `@latest` pointing to the | ||
| most recent tagged release. | ||
| 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. | ||
| 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` | ||
| Shoelace is an UI library that is exported directly from `@hotosm/ui`. | ||
| ### ES Modules | ||
| 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>): | ||
| - 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`: | ||
| ```js | ||
| import '@hotosm/ui/components/button/button'; | ||
| ``` | ||
| ```json | ||
| "peerDependencies": { | ||
| "@shoelace-style/shoelace": "^2.15.1" | ||
| } | ||
| ``` | ||
| And then: | ||
| > Ideally the version of Shoelace installed should match the version used in | ||
| > hotosm/ui. | ||
| ```html | ||
| <hot-button disabled variant="secondary">Can't Click Me</hot-button> | ||
| ``` | ||
| Example: | ||
| Or | ||
| ```js | ||
| import '@hotosm/ui/components/header/header'; | ||
| // Then in your template | ||
| <hot-header @login="${someFunction()}"></hot-header> | ||
| import { Button } from '@hotosm/ui/components'; | ||
| ``` | ||
| ### 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`: | ||
| And then: | ||
| ```bash | ||
| pnpm install @hotosm/ui | ||
| ```html | ||
| <Button disabled variant="secondary">Can't Click Me</Button> | ||
| ``` | ||
| ```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; | ||
| ``` | ||
| ### Development | ||
| > Note that while web components must always have a closing tag, this is not | ||
| > required for the React wrappers. | ||
| HOT UI is developed in TypeScript, using Lit and @lit/react. | ||
| ## Using Extra Shoelace Components | ||
| Primarily we want to have: | ||
| 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. | ||
| - 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. | ||
| Shoelace is an excellent UI library that is exported directly from `@hotosm/ui`. | ||
| ### Examples | ||
| 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>): | ||
| You can found examples for HTML and also all common frameworks (React, Svelte, Vue) under `/examples`. | ||
| ```js | ||
| import '@hotosm/ui/components/button/button'; | ||
| ### How to contribute | ||
| // Then in your template | ||
| <hot-button disabled variant="secondary">Can't Click Me</hot-button> | ||
| ``` | ||
| - Clone the project `git clone [email protected]:hotosm/ui.git` | ||
| - Install dependencies `pnpm install` | ||
| - Run the storybook `pnpm run dev` | ||
| - Write code! | ||
| If you are using a bundler, you must bundle the (icon) assets yourself, | ||
| described in the Shoelace docs. | ||
| There's also a React storybook that you can use for testing: | ||
| ### Example of bundling assets | ||
| - Run the React storybook `pnpm run dev-react` | ||
| - To include the Shoelace assets in your final bundle (dist), you could add | ||
| the following to your `package.json`: | ||
| For **styling**, we have 2 important files under `/theme`: | ||
| ```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", | ||
| } | ||
| ``` | ||
| - `hot-sl.css` has a Shoelace theme, re-defining some variables | ||
| - `hot.css` has custom styles for eveything else, specially composited components | ||
| ### 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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.