-
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
1 parent
8f10a00
commit fc508cc
Showing
2 changed files
with
149 additions
and
159 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 |
|---|---|---|
|
|
@@ -47,169 +47,34 @@ currently written in **Lit**, using TypeScript. | |
|
|
||
| ## Install | ||
|
|
||
| Via NPM: | ||
| ### Via NPM | ||
|
|
||
| ```bash | ||
| npm install @hotosm/ui | ||
| - Install package `@hotosm/ui` as a dependency in your `package.json`. | ||
| - Import the components and styles. | ||
|
|
||
| yarn add @hotosm/ui | ||
| ```html | ||
| <script> | ||
| import '@hotosm/ui/dist/styles.css'; | ||
| import Toolbar from '@hotosm/ui/dist/components.js'; | ||
| </script> | ||
|
|
||
| pnpm install @hotosm/ui | ||
| // Use the components in your templates | ||
| <hot-button disabled> </hot-button> | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ### CDN (HTML / HTMX) | ||
| ### Via CDN | ||
|
|
||
| ```html | ||
| // Import Shoelace dependency | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://cdn.jsdelivr.net/npm/@shoelace-style | ||
| /[email protected]/cdn/themes/light.css" /> | ||
| <script | ||
| type="module" | ||
| src="https://cdn.jsdelivr.net/npm/@shoelace-style/ | ||
| [email protected]/cdn/shoelace-autoloader.js" | ||
| ></script> | ||
|
|
||
| // Import the components & styles (or add your own styling) | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://s3.amazonaws.com/hotosm-ui/latest/theme/styles.css" | ||
| href="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/styles.css" | ||
| /> | ||
| <script | ||
| type="module" | ||
| src="https://s3.amazonaws.com/hotosm-ui/latest/components/Button.js" | ||
| src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js" | ||
| ></script> | ||
|
|
||
| <div> | ||
| <hot-button disabled> </hot-button> | ||
| </div> | ||
| <hot-button disabled> </hot-button> | ||
| ``` | ||
|
|
||
| > Using the Shoelace autoloader will lazy load only the components you use. | ||
| See the docs for more [usage examples](https://hotosm.github.io/ui/usage/). | ||
|
|
||
| > Components are versioned under subdirectories, with /latest/ tracking the | ||
| > `main` branch, plus versioned releases. | ||
| ### ES6 Imports (most frameworks) | ||
|
|
||
| Install your required version with a pin, or latest: | ||
|
|
||
| ```bash | ||
| pnpm install @hotosm/ui | ||
| ``` | ||
|
|
||
| ```js | ||
| <script> | ||
| import '@hotosm/ui/theme/styles.css' | ||
| import '@hotosm/ui/components/Button' | ||
| </script> | ||
|
|
||
| <hot-button disabled></hot-button> | ||
| ``` | ||
|
|
||
| > Note that web components must always have a closing tag. | ||
| #### Importing Icons | ||
|
|
||
| The icon pack for Shoelace must be imported to display in components. | ||
|
|
||
| There are two options: | ||
|
|
||
| ##### 1. CDN Assets | ||
|
|
||
| Just add the Shoelace icons via CDN in your HTML file: | ||
|
|
||
| ```html | ||
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style | ||
| /[email protected]/cdn/themes/light.css" /> | ||
|
|
||
| // Or dark | ||
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style | ||
| /[email protected]/cdn/themes/dark.css" /> | ||
| ``` | ||
|
|
||
| ##### 2. Bundle Assets Yourself | ||
|
|
||
| - Add Shoelace as a `peerDependency` and to your `package.json`: | ||
|
|
||
| ```json | ||
| "peerDependencies": { | ||
| "@shoelace-style/shoelace": "^2.15.1" | ||
| } | ||
| ``` | ||
|
|
||
| - Also add `vite-plugin-static-copy` as a devDependency: | ||
| `pnpm install -D vite-plugin-static-copy` | ||
| - Add to your `vite.config.ts`: | ||
|
|
||
| ```js | ||
| import { viteStaticCopy } from 'vite-plugin-static-copy'; | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [ | ||
| viteStaticCopy({ | ||
| targets: [ | ||
| { | ||
| src: 'node_modules/@shoelace-style/shoelace/dist/assets', | ||
| dest: '' | ||
| } | ||
| ] | ||
| }), | ||
| ], | ||
| ``` | ||
|
|
||
| - Now the Shoelace assets will be bundled with your dist, under `/shoelace`. | ||
|
|
||
| #### 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`: | ||
|
|
||
| ```bash | ||
| pnpm install @hotosm/ui | ||
| ``` | ||
|
|
||
| ```js | ||
| import { Button } from '@hotosm/ui/react/Button' | ||
|
|
||
| const HomePage = ({}) => { | ||
| return ( | ||
| <div className="your-css-classes"> | ||
| <div | ||
| ... | ||
| > | ||
| <Button disabled /> | ||
| </div> | ||
| </div> | ||
| ); | ||
| }; | ||
|
|
||
| export default HomePage; | ||
| ``` | ||
|
|
||
| ## Using Extra Shoelace Components | ||
|
|
||
| The UI library is not comprehensive & you may wish to use additional components | ||
| from Shoelace in your app. | ||
|
|
||
| Ideally you should install the same version of @shoelace-style/shoelace as this | ||
| library. | ||
|
|
||
| To determine which version: | ||
|
|
||
| - View the | ||
| [@hotosm/ui](https://www.npmjs.com/package/@hotosm/ui?activeTab=versions) | ||
| package on npmjs.com. | ||
| - Select the version you are using. | ||
| - Go to the `Code` tab, then open the `package.json` file. | ||
| - The version of shoelace used should be in the `dependencies` section. | ||
|
|
||
| If you are using a bundler, you must bundle the (icon) assets yourself, | ||
| as described above. | ||
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,44 +1,169 @@ | ||
| # Usage | ||
|
|
||
| It production either the HOT S3-based CDN can be used, or JSDelivr. | ||
| ## NPM vs CDN | ||
|
|
||
| ## ES6 Modules (NPM Package) | ||
| The components are distributed as both ES Modules for import in an application | ||
| that will be bundled later (by rollup, vite, webpack, etc), and also as pre-compiled | ||
| bundles for use in cases where a bundler is not involved (e.g. direct HTML). | ||
|
|
||
| The recommended approach if possible, see the [README](./index.md). | ||
| While it is possible to use either the ES Modules or compiled bundle via either NPM | ||
| install or CDN loading, it is recommended to use the modules with a bundler and the | ||
| CDN for use in HTML / Markdown / HTMX. | ||
|
|
||
| ## AWS S3 CDN | ||
| ## ES Modules | ||
|
|
||
| Using the ES Modules will allow for cherry-picking of only the required components | ||
| that your app requires, in addition to tree-shaking in the final bundle | ||
| (removing unused code). | ||
|
|
||
| ### Importing Icons | ||
|
|
||
| The icon pack for Shoelace must be imported to display in components. | ||
|
|
||
| There are two options: | ||
|
|
||
| #### 1. CDN Assets | ||
|
|
||
| Just add the Shoelace icons via CDN in your HTML file: | ||
|
|
||
| ```html | ||
| // Import the components | ||
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style | ||
| /[email protected]/cdn/themes/light.css" /> | ||
|
|
||
| // Or dark | ||
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style | ||
| /[email protected]/cdn/themes/dark.css" /> | ||
| ``` | ||
|
|
||
| #### 2. Bundle Assets Yourself | ||
|
|
||
| - Add Shoelace as a `peerDependency` and to your `package.json`: | ||
|
|
||
| ```json | ||
| "peerDependencies": { | ||
| "@shoelace-style/shoelace": "^2.15.1" | ||
| } | ||
| ``` | ||
|
|
||
| - Also add `vite-plugin-static-copy` as a devDependency: | ||
| `pnpm install -D vite-plugin-static-copy` | ||
| - Add to your `vite.config.ts`: | ||
|
|
||
| ```js | ||
| import { viteStaticCopy } from 'vite-plugin-static-copy'; | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [ | ||
| viteStaticCopy({ | ||
| targets: [ | ||
| { | ||
| src: 'node_modules/@shoelace-style/shoelace/dist/assets', | ||
| dest: '' | ||
| } | ||
| ] | ||
| }), | ||
| ], | ||
| ``` | ||
|
|
||
| - Now the Shoelace assets will be bundled with your dist, under `/shoelace`. | ||
|
|
||
| ### 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`: | ||
|
|
||
| ```bash | ||
| pnpm install @hotosm/ui | ||
| ``` | ||
|
|
||
| ```js | ||
| import { Button } from '@hotosm/ui/react/Button' | ||
|
|
||
| const HomePage = ({}) => { | ||
| return ( | ||
| <div className="your-css-classes"> | ||
| <div | ||
| ... | ||
| > | ||
| <Button disabled /> | ||
| </div> | ||
| </div> | ||
| ); | ||
| }; | ||
|
|
||
| export default HomePage; | ||
| ``` | ||
|
|
||
| > Note that while web components must always have a closing tag, this is not | ||
| > required for the React wrappers. | ||
| ## CDN | ||
|
|
||
| ### AWS | ||
|
|
||
| Versions published under `https://s3.amazonaws.com/hotosm-ui/latest` track the `main` | ||
| branch of the repo. | ||
|
|
||
| The example below imports the ES Modules: | ||
|
|
||
| ```html | ||
| // Import only the button component | ||
| <script | ||
| type="module" | ||
| src="https://s3.amazonaws.com/hotosm-ui/latest/components/Button.js" | ||
| ></script> | ||
|
|
||
| // Import the styles (or create your own) | ||
| // Import the styles (or import custom styles) | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://s3.amazonaws.com/hotosm-ui/latest/theme/styles.css" | ||
| href="https://s3.amazonaws.com/hotosm-ui/latest/dist/styles.css" | ||
| /> | ||
|
|
||
| <hot-button>Click Me!</hot-button> | ||
| ``` | ||
|
|
||
| ## JSDelivr (NPM CDN) | ||
| ## JSDelivr (provided by NPM) | ||
|
|
||
| This only includes the package releases, with `@latest` pointing to the most | ||
| recent tagged release. | ||
|
|
||
| The example below imports the compiled bundle (i.e. all components and styles): | ||
|
|
||
| ```html | ||
| <script | ||
| type="module" | ||
| src="https://cdn.jsdelivr.net/gh/hotosm/ui@latest/Button.js" | ||
| src="https://cdn.jsdelivr.net/gh/hotosm/ui@latest/dist/components.js" | ||
| ></script> | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://cdn.jsdelivr.net/gh/hotosm/ui@latest/theme/styles.css" | ||
| href="https://cdn.jsdelivr.net/gh/hotosm/ui@latest/dist/styles.css" | ||
| /> | ||
|
|
||
| <hot-button>Click Me!</hot-button> | ||
| ``` | ||
|
|
||
| ## Using Extra Shoelace Components | ||
|
|
||
| The UI library is not comprehensive & you may wish to use additional components | ||
| from Shoelace in your app. | ||
|
|
||
| Ideally you should install the same version of @shoelace-style/shoelace as this | ||
| library. | ||
|
|
||
| To determine which version: | ||
|
|
||
| - View the | ||
| [@hotosm/ui](https://www.npmjs.com/package/@hotosm/ui?activeTab=versions) | ||
| package on npmjs.com. | ||
| - Select the version you are using. | ||
| - Go to the `Code` tab, then open the `package.json` file. | ||
| - The version of shoelace used should be in the `dependencies` section. | ||
|
|
||
| If you are using a bundler, you must bundle the (icon) assets yourself, | ||
| as described above. | ||
|
|
||
| ## Example Component In Markdown | ||
|
|
||
| <!-- markdownlint-disable --> | ||
|
|
||