From d1f29aaf088de575bab8e41c7ded6c62b70f00c4 Mon Sep 17 00:00:00 2001
From: spwoodcock <sam.woodcock@protonmail.com>
Date: Fri, 31 May 2024 14:44:02 +0100
Subject: [PATCH] docs: move all usage info to readme

---
 README.md     | 146 ++++++++++++++++++++++++++++++++++++++---
 docs/usage.md | 178 --------------------------------------------------
 mkdocs.yml    |   1 -
 3 files changed, 136 insertions(+), 189 deletions(-)
 delete mode 100644 docs/usage.md

diff --git a/README.md b/README.md
index 0a790e0..d2700bc 100644
--- a/README.md
+++ b/README.md
@@ -47,28 +47,33 @@ currently written in **Lit**, using TypeScript.
 
 ## Install
 
-### Via NPM
+There are two options for install:
+
+- **NPM**: appropriate for applications that have installable dependencies.
+- **CDN**: appropriate for HTML / Markdown / HTMX.
+
+### Components Bundle
+
+- This is the compiled JavaScript bundle generated from the TypeScript code.
+- The components require no additional dependencies and are minified.
+
+#### Via NPM
 
 - Install package `@hotosm/ui` as a dependency in your `package.json`.
-- Import the components and styles.
+- Import the components.
 
 ```html
 <script>
-  import '@hotosm/ui/dist/styles.css';
-  import Toolbar from '@hotosm/ui/dist/components.js';
+  import '@hotosm/ui/dist/components.js';
 </script>
 
 // Use the components in your templates
 <hot-button disabled> </hot-button>
 ```
 
-### Via CDN
+#### Via CDN
 
 ```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/styles.css"
-/>
 <script
   type="module"
   src="https://cdn.jsdelivr.net/npm/@hotosm/ui@latest/dist/components.js"
@@ -77,4 +82,125 @@ currently written in **Lit**, using TypeScript.
 <hot-button disabled> </hot-button>
 ```
 
-See the docs for more [usage examples](https://hotosm.github.io/ui/usage/).
+The `jsdelivr` CDN only includes package releases, with `@latest` pointing to the
+most recent tagged release.
+
+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`
+
+### ES Modules
+
+- 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`:
+
+    ```json
+      "peerDependencies": {
+        "@shoelace-style/shoelace": "^2.15.1"
+      }
+    ```
+
+    > Ideally the version of Shoelace installed should match the version used in
+    > hotosm/ui.
+
+- This will also install subdependencies such as Lit.
+- If there is a conflict between Lit versions, the `lit` package can also be pinned
+  via `peerDependency`.
+
+Example:
+
+```js
+import '@hotosm/ui/components/Toolbar';
+
+// Then in your template
+<hot-button>Click Me</hot-button>
+```
+
+### 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.
+
+## 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 (particularly if using the ES Modules)
+
+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,
+described in the Shoelace docs.
+
+### Example of bundling assets
+
+- To include the Shoelace assets in your final bundle (dist), you could add
+  the following to your `package.json`:
+
+```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",
+  }
+```
+
+- Now the Shoelace assets will be bundled with your dist, under `/shoelace`.
+- Following the example, also add `public/assets/icons` to your `.gitignore` file.
+
+## Example Markdown Components
+
+<!-- markdownlint-disable -->
+
+<hot-button id="hotButton">Click Me!</hot-button>
+<script>
+  const button = document.getElementById('hotButton');
+
+  button.addEventListener('click', () => {
+    alert('Button Clicked!');
+  });
+</script>
+
+<br>
+
+<hot-toolbar></hot-toolbar>
+
+<!-- markdownlint-enable -->
diff --git a/docs/usage.md b/docs/usage.md
deleted file mode 100644
index 6e2090b..0000000
--- a/docs/usage.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# Usage
-
-## NPM vs CDN
-
-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).
-
-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.
-
-## 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.
-
-#### 1. Loading Assets from CDN
-
-If the component is imported via CDN, the icons will be bundled automatically:
-
-```js
-import "https://cdn.jsdelivr.net/npm/@shoelace-style
-/shoelace@2.15.1/cdn/components/Button.js"
-```
-
-#### 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 import custom styles)
-<link
-  rel="stylesheet"
-  href="https://s3.amazonaws.com/hotosm-ui/latest/dist/styles.css"
-/>
-
-<hot-button>Click Me!</hot-button>
-```
-
-## 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/npm/@hotosm/ui@latest/dist/components.js"
-></script>
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@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 Markdown Components
-
-<!-- markdownlint-disable -->
-
-<hot-button id="hotButton">Click Me!</hot-button>
-<script>
-  const button = document.getElementById('hotButton');
-
-  button.addEventListener('click', () => {
-    alert('Button Clicked!');
-  });
-</script>
-
-<br>
-
-<hot-toolbar></hot-toolbar>
-
-<!-- markdownlint-enable -->
diff --git a/mkdocs.yml b/mkdocs.yml
index b4917d9..875257f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -65,7 +65,6 @@ nav:
       - Header: components/hot-header.md
       - Toolbar: components/hot-toolbar.md
       - Tracking: components/hot-tracking.md
-  - Usage: usage.md
   - Storybook: storybook.md
   - License: LICENSE.md
   - Changelog: CHANGELOG.md