Skip to content

Latest commit

 

History

History
188 lines (137 loc) · 5.42 KB

README.md

File metadata and controls

188 lines (137 loc) · 5.42 KB
Raw

HOT Shared UI

HOT

Shared Web Components with theming for use across HOTOSM tools.

Publish CDN Deploy Publish Docs Package version Downloads License

📖 Documentation: https://hotosm.github.io/ui/

🖥️ Source Code: https://github.com/hotosm/ui

🎯 Roadmap / Tasks: https://github.com/orgs/hotosm/projects/37/views/3

Shared UI Components with HOT Theming

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.

They are available as Web Components with support for usage in almost all modern web frameworks.

The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance.

Quick start

There are two options: NPM and Components Bundle.

NPM

Appropriate for applications that have installable dependencies

npm install @hotosm/ui

Import the library in your project and use the components.

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

React

  import { Logo } from '@hotosm/ui/components/react';
<Logo />

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.

<link
  rel="stylesheet"
  href="https://s3.amazonaws.com/hotosm-ui/latest/style.css"
/>

<script
  type="module"
  src="https://s3.amazonaws.com/hotosm-ui/latest/dist/hotosm-ui.js"
></script>

<hot-logo></hot-logo>

Using Extra Shoelace Components

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.

Shoelace is an UI library that is exported directly from @hotosm/ui.

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):

import '@hotosm/ui/components/button/button';
<hot-button disabled variant="secondary">Can't Click Me</hot-button>

React Shoelace Wrappers

import { Button } from '@hotosm/ui/components';
<Button disabled variant="secondary">Can't Click Me</Button>

Examples

You can found examples for HTML and also all common frameworks (React, Svelte, Vue) under /examples.

Development

HOT UI is developed in TypeScript, using Lit and @lit/react.

Primarily we want to have:

  • 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.

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!

There's also a React storybook that you can use for testing:

  • Run the React storybook pnpm run dev-react

For styling, we have 2 important files under /theme:

  • hot-sl.css has a Shoelace theme, re-defining some variables
  • hot.css has custom styles for eveything else, specially composited components

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.