@hotosm/ui 0.2.0-a6 → 0.2.0-a7

package/README.md

@@ -59,35 +59,43 @@ pnpm install @hotosm/ui
 
 ## Usage
 
-### HTML / HTMX
+### CDN (HTML / HTMX)
 
 ```html
-// Import the components
+// Import Shoelace dependency
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style
+  /shoelace@2.15.1/cdn/themes/light.css" />
 <script
   type="module"
-  src="https://s3.amazonaws.com/hotosm-ui/latest/components/Button.js"
+  src="https://cdn.jsdelivr.net/npm/@shoelace-style/
+  shoelace@2.15.1/cdn/shoelace-autoloader.js"
 ></script>
 
-// Import the styles (or create your own)
+// Import the components & styles (or add your own styling)
 <link
   rel="stylesheet"
   href="https://s3.amazonaws.com/hotosm-ui/latest/theme/hot.css"
 />
+<script
+  type="module"
+  src="https://s3.amazonaws.com/hotosm-ui/latest/components/Button.js"
+></script>
 
 <div>
   <hot-button disabled> </hot-button>
 </div>
 ```
 
+> 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/).
 
-> core.js will contain the minimal low level components.
->
-> extra.js will contain additional wrapper components.
->
-> There should be versioning of the components, plus a /latest/ version too.
+> Components are versioned under subdirectories, with /latest/ tracking the
+> `main` branch, plus versioned releases.
 
-### React
+### ES6 Imports (most frameworks)
 
 Install your required version with a pin, or latest:
 
@@ -96,7 +104,80 @@ pnpm install @hotosm/ui
 ```
 
 ```js
-import '@hotosm/ui/components/Button'
+<script>
+  import '@hotosm/ui/theme/hot.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
+/shoelace@2.15.1/cdn/themes/light.css" />
+
+// Or dark
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style
+/shoelace@2.15.1/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 (
@@ -104,8 +185,7 @@ const HomePage = ({}) => {
       <div
         ...
       >
-        <hot-button disabled>
-        </hot-button>
+        <Button disabled />
       </div>
     </div>
   );

package/components/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Button } from './Button';
+export { default as Toolbar } from './Toolbar';
+export { default as Tracking } from './Tracking';

package/components/index.js

@@ -0,0 +1,5 @@
+// Index to import all components together
+// import '@hotosm/ui/components';
+export { default as Button } from './Button';
+export { default as Toolbar } from './Toolbar';
+export { default as Tracking } from './Tracking';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotosm/ui",
-  "version": "0.2.0a6",
+  "version": "0.2.0a7",
   "description": "Shared UI components with theming for use across HOTOSM tools.",
   "type": "module",
   "engines": {

package/react/Button.d.ts

@@ -0,0 +1,2 @@
+declare const reactWrapper: React.ForwardRefExoticComponent<any>;
+export default reactWrapper;

package/react/Button.js

@@ -0,0 +1,14 @@
+// @ts-ignore
+import * as React from 'react';
+import { createComponent } from '@lit/react';
+import Button from '../components/Button';
+const reactWrapper = createComponent({
+    tagName: 'hot-button',
+    elementClass: Button,
+    react: React,
+    events: {
+        onClick: 'click',
+    },
+    displayName: 'hot-button'
+});
+export default reactWrapper;

package/react/Toolbar.d.ts

@@ -0,0 +1,2 @@
+declare const reactWrapper: React.ForwardRefExoticComponent<any>;
+export default reactWrapper;

package/react/Tracking.d.ts

@@ -0,0 +1,2 @@
+declare const reactWrapper: React.ForwardRefExoticComponent<any>;
+export default reactWrapper;

package/react/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Button } from './Button';
+export { default as Toolbar } from './Toolbar';
+export { default as Tracking } from './Tracking';

package/react/index.js

@@ -0,0 +1,5 @@
+// Index to import all components together
+// import '@hotosm/ui/react';
+export { default as Button } from './Button';
+export { default as Toolbar } from './Toolbar';
+export { default as Tracking } from './Tracking';

package/react/HotToolbar.d.ts

@@ -1,12 +0,0 @@
-import Toolbar from '../components/Toolbar';
-declare const reactWrapper: import("@lit/react").ReactWebComponent<Toolbar, {
-    onHotUndoClick: string;
-    onHotRedoClick: string;
-    onHotBoldClick: string;
-    onHotItalicClick: string;
-    onHotUnderlineClick: string;
-    onHotLeftalignClick: string;
-    onHotCenteralignClick: string;
-    onHotRightalignClick: string;
-}>;
-export default reactWrapper;

package/react/HotTracking.d.ts

@@ -1,6 +0,0 @@
-import Tracking from '../components/Tracking';
-declare const reactWrapper: import("@lit/react").ReactWebComponent<Tracking, {
-    onHotAgree: string;
-    onHotDisagree: string;
-}>;
-export default reactWrapper;