@hotosm/ui

v0.3.4-b3

Published

a month ago

Shared UI components with HOT theming.

0High
0Medium
0Low

HOT Shared UI

Shared UI Components with HOT Theming

This repository contains advice on how to use the WebAwesome Web Components library, references to the HOTOSM style guide, and a few 'wrapper' components to assist development:

Reduced code duplication across HOT tools (we repeat a lot!)
Simplified developer experience to create a HOT app.
Reasonably consistent theming and style across tools.

The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance. It should include a minimal number of components, such as:

Header, including auth flows (OSM, Google) and login info.
Sidebar with links to extra resources.
Footer with links.

Quick start

Current HOTOSM UI version used: 0.3.1-b5 Current WebAwesome version used: 3.0.0-beta.1

Install WebAwesome

pnpm install "@awesome.me/[email protected]"

[!NOTE] It's important to pin the version of web awesome used to the version in this library, to avoid any conflicts and incompatibilities between components.

Install HOT Components

pnpm install "@hotosm/ui"

Configure The Styles

In your index.html or equivalent frontend root, add the following classes to your <html> block:

<!DOCTYPE html>
<html class="wa-theme-default wa-palette-hotosm wa-brand-red wa-neutral-gray
  wa-success-cyan wa-warning-yellow wa-danger-orange">
  <head>
    xxx
  </head>
  <body>
    xxx
  </body>
</html>

[!IMPORTANT] These classes determine the colour usage for different component variants, and probably should not be changed!

And import the required styles in your main.ts or equivalent (we import from package rather than CDN, to allow the bundler to work its CSS tree-shaking magic).

import '@hotosm/ui/dist/style.css';

If you wish to use any of the variables in hot.css manually, you can reference them as variables like so:

/* In your CSS file */
some-param: var(--hot-some-param);
/* See all variables in the `theme/hot.css` file */

Use The Components

Via Bundler

Import each component individually into your code:

<script>
  import '@hotosm/ui/dist/components/header/header.js';
</script>

<hot-header
  param1=""
  param2=""
>
</hot-header>

Via CDN

If you are working directly in HTML, or other ways without a configured bundler, you can import all the components as a bundle, as use them like so:

<script>
  import '@hotosm/ui/dist/style.css';
  import '@hotosm/ui/dist/hotosm-ui';
</script>

<hot-header title="Test App" size="small" showLogin="false"></hot-header>

React

Import in the same way as the bundler example above, except events are bound to slightly differently:

<hot-header
  title="Test App"
  size="small"
  showLogin="false"
  onLogin={() => {
    console.log('handler');
  }}
></hot-header>

Component Guides

Header: see /header.md for detailed integration, styling, and framework examples.

How to contribute

Clone the project git clone [email protected]:hotosm/ui.git
Install dependencies pnpm install
Run the storybook pnpm run dev
Write code!

For styling, check /theme:

hot.css has a HOT theme, used across HOT components.
hot-wa-override.css has a WebAwesome theme, re-defining style variables.

License

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.