docs: move all usage info to readme

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

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