diff --git a/README.md b/README.md index 3267108..0a790e0 100644 --- a/README.md +++ b/README.md @@ -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 + -pnpm install @hotosm/ui +// Use the components in your templates + ``` -## Usage - -### CDN (HTML / HTMX) +### Via CDN ```html -// Import Shoelace dependency - - -// Import the components & styles (or add your own styling) - -
- -
+ ``` -> 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 - - - -``` - -> 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 - - -// Or dark - -``` - -##### 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 ( -
-
-
-
- ); -}; - -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. diff --git a/docs/usage.md b/docs/usage.md index a16cd0b..d22cbfe 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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 + + +// Or dark + +``` + +#### 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 ( +
+
+
+
+ ); +}; + +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 -// Import the styles (or create your own) +// Import the styles (or import custom styles) Click Me! ``` -## 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 Click Me! ``` +## 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