diff --git a/README.md b/README.md index 0d36744..22d5f89 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,80 @@ -# HOT Shared UI - - -

- HOT -

-

- Shared Web Components with theming for use across HOTOSM tools. -

-

- - Publish - - - CDN Deploy - - - Publish Docs - - - Package version - - - Downloads - - - License - -

+# HOT UI -📖 **Documentation**: https://hotosm.github.io/ui/ +## Shared UI components with HOT theming. -🖥️ **Source Code**: https://github.com/hotosm/ui +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**: https://github.com/orgs/hotosm/projects/37/views/3 +The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance. ---- + - +[![Release](https://github.com/hotosm/ui/actions/workflows/publish.yml/badge.svg?event=release)](https://github.com/hotosm/ui/actions/workflows/publish.yml/) +[![CDN Deploy](https://github.com/hotosm/ui/actions/workflows/cdn_deploy.yml/badge.svg?branch=main)](https://github.com/hotosm/ui/actions/workflows/cdn_deploy.yml) +[![Docs](https://github.com/hotosm/ui/actions/workflows/docs.yml/badge.svg)](https://github.com/hotosm/ui/actions/workflows/docs.yml) +[![Package Version](https://img.shields.io/npm/v/%40hotosm/ui?color=334D058)](https://www.npmjs.com/package/@hotosm/ui) +[![Downloads](https://img.shields.io/npm/dm/%40hotosm%2Fui)](https://npmtrends.com/@hotosm/ui) +[![License](https://img.shields.io/github/license/hotosm/ui.svg)](https://github.com/hotosm/ui/blob/main/LICENSE.md) -Shared UI components with theming for use across HOTOSM tools, -to reduce code duplication. +📖 **Documentation**: https://hotosm.github.io/ui/ -The components are -[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), -currently written in **Lit**, using TypeScript. +🖥️ **Source Code**: https://github.com/hotosm/ui -The main goal of this project is not to re-invent the wheel, or add an extra -burden of development and maintenance. +🎯 **Roadmap / Tasks**: https://github.com/orgs/hotosm/projects/37/views/3 -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 +``` + +Or: + +```js + import { Button } from '@hotosm/ui/components'; +``` + +And use the components: + +```html +Click me! +``` + +Or: -// Use the components in your templates - +```html + ``` +### 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 - +``` +## 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] +(): -- 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 +Can't Click Me +``` -Example: +Or ```js -import '@hotosm/ui/components/header/header'; - -// Then in your template - +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 + ``` -```js -import { Button } from '@hotosm/ui/react/Header' - -const HomePage = ({}) => { - return ( -
-
-
-
-
- ); -}; - -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] -(): +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 -Can't Click Me -``` +- Clone the project `git clone git@github.com: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. \ No newline at end of file diff --git a/package.json b/package.json index 2bb7969..fc272f0 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@hotosm/ui", - "version": "0.2.04", - "description": "Shared UI components with theming for use across HOTOSM tools.", + "version": "0.2.05", + "description": "Shared UI components with HOT theming.", "type": "module", "engines": { "node": ">=14.17" diff --git a/theme/logo/hot-logo-png.png b/theme/logo/hot-logo-png.png new file mode 100644 index 0000000..b069604 Binary files /dev/null and b/theme/logo/hot-logo-png.png differ