@pixelmatters/markup 1.1.0 → 1.3.0

package/README.md

@@ -17,25 +17,45 @@ Pin-anchored feedback for live web apps. Drop in a script tag (or one React comp
 - **Respects the platform** — honours `prefers-reduced-motion` and `prefers-color-scheme`; full keyboard navigation with focus traps in popovers.
 - **Tiny surface, tiny config** — `init({ apiUrl, apiKey })` is enough to start. No global CSS to import, no provider to wrap.
 
-Built with [Preact](https://preactjs.com). Ships as ESM with a vanilla entry and a React/Preact wrapper.
+Built with [Preact](https://preactjs.com). Ships as a single ESM bundle — wire it into any framework with a one-liner in your root component (snippets below).
 
 ## Install
 
 ```bash
 # pnpm
-pnpm install @pixelmatters/markup
+pnpm add @pixelmatters/markup
 # or yarn
 yarn add @pixelmatters/markup
 # or npm
 npm install @pixelmatters/markup
 ```
 
-CDN drop-in (auto-init on `DOMContentLoaded`):
+CDN drop-in (no build step) — paste this just before `</body>`:
+
+```html
+<script type="module">
+  // Pin the exact version — esm.sh resolves it from npm
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.3.0'
+  // or
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.3.0'
+
+  init({
+    apiUrl: 'https://your-deployment.convex.site',
+    apiKey: 'markup_...',
+    position: 'bottom-right', // optional
+    theme: 'auto', // optional
+  })
+</script>
+```
+
+> **Why pin the version?** CDN URLs without a version (`@pixelmatters/markup`) resolve to whatever's `latest` on npm — a future major release will break your page silently. Always pin (`@pixelmatters/markup@1.3.0`).
+
+If your platform doesn't allow inline JS (some CMS / page-builder editors), use the auto-init form instead — point a `<script src=…>` at the bundle and pass config via `data-*` attributes:
 
 ```html
 <script
   type="module"
-  src="https://unpkg.com/@pixelmatters/markup"
+  src="https://esm.sh/@pixelmatters/markup@1.3.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -43,7 +63,7 @@ CDN drop-in (auto-init on `DOMContentLoaded`):
 ></script>
 ```
 
-The `data-markup-widget="true"` attribute is required — it's how the bootstrap locates its own `<script>` tag (since `document.currentScript` is `null` for `type="module"`).
+`data-markup-widget="true"` is required — it's how the bootstrap finds its own `<script>` tag (since `document.currentScript` is `null` for `type="module"`).
 
 ## Quickstart
 
@@ -63,23 +83,60 @@ const stop = init({
 stop() // equivalent to destroy()
 ```
 
-### React / Preact
+### React
 
 ```tsx
-import { MarkupWidget } from '@pixelmatters/markup/react'
+import { useEffect } from 'react'
+import { init } from '@pixelmatters/markup'
 
 export default function App() {
-  return (
-    <>
-      {/* your app */}
-      <MarkupWidget
-        apiUrl={import.meta.env.VITE_MARKUP_API_URL}
-        apiKey={import.meta.env.VITE_MARKUP_API_KEY}
-        position="bottom-right" // optional
-        theme="light" // optional
-      />
-    </>
-  )
+  useEffect(() => {
+    return init({
+      apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+      apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+      position: 'bottom-right', // optional
+      theme: 'auto', // optional
+    })
+  }, [])
+
+  return <>{/* your app */}</>
+}
+```
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { onMounted, onBeforeUnmount } from 'vue'
+import { init } from '@pixelmatters/markup'
+
+let stop: (() => void) | undefined
+onMounted(() => {
+  stop = init({
+    apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+    apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+  })
+})
+onBeforeUnmount(() => stop?.())
+</script>
+```
+
+### SolidJS
+
+```tsx
+import { onMount, onCleanup } from 'solid-js'
+import { init } from '@pixelmatters/markup'
+
+export default function App() {
+  onMount(() => {
+    const stop = init({
+      apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+      apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+    })
+    onCleanup(stop)
+  })
+
+  return <>{/* your app */}</>
 }
 ```
 
@@ -89,23 +146,25 @@ export default function App() {
 
 Mounts the widget. Idempotent: re-calling with the same config is a no-op; calling with a different config tears down the previous instance first. Returns the `destroy` function.
 
-| Option     | Type                              | Default          | Description                                                                                             |
-| ---------- | --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
-| `apiUrl`   | `string`                          | required         | Convex deployment site URL (`https://*.convex.site`)                                                    |
-| `apiKey`   | `string`                          | required         | Project API key — mint one in the dashboard                                                             |
-| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Where the floating action button sits                                                                   |
-| `theme`    | `'light' \| 'dark' \| 'auto'`     | `'auto'`         | Visual theme — `'light'` or `'dark'`, or `'auto'` (default) to follow the host's `prefers-color-scheme` |
+| Option     | Type                              | Default          | Description                                                                                                              |
+| ---------- | --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `apiUrl`   | `string`                          | required         | Convex deployment site URL (`https://*.convex.site`)                                                                     |
+| `apiKey`   | `string`                          | required         | Project API key — mint one in the dashboard                                                                              |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Initial corner for the floating action button — users can drag it across the viewport midline to flip corners at runtime |
+| `theme`    | `'light' \| 'dark' \| 'auto'`     | `'auto'`         | Visual theme — `'light'` or `'dark'`, or `'auto'` (default) to follow the host's `prefers-color-scheme`                  |
 
 ### `destroy()`
 
 Unmounts the widget and removes the host element. Safe to call when nothing is mounted.
 
-### Keyboard
+### Keyboard & mouse
 
-| Shortcut           | Action                                          |
-| ------------------ | ----------------------------------------------- |
-| `cmd/ctrl + .`     | Toggle HUD visibility                           |
-| `cmd/ctrl + click` | Click the FAB to hide the HUD with a hint toast |
+| Shortcut              | Action                                                                 |
+| --------------------- | ---------------------------------------------------------------------- |
+| `cmd/ctrl + .`        | Toggle HUD visibility                                                  |
+| `cmd/ctrl + click`    | Click the FAB to hide the HUD with a hint toast                        |
+| Drag the FAB          | Snap it to whichever bottom corner the pointer ends in                 |
+| Drag a popover header | Move the open thread / new-thread popover; resets to the pin on reopen |
 
 ## How it works
 
@@ -154,8 +213,6 @@ A drop-in feedback widget published on npm as `@pixelmatters/markup`. It mounts
 
 ```ts
 import { init, destroy } from '@pixelmatters/markup'
-// or:
-import { MarkupWidget } from '@pixelmatters/markup/react'
 
 init({
   apiUrl: string,                            // required
@@ -165,12 +222,32 @@ init({
 }) // returns a destroy() function — call it on unmount / logout / route teardown
 ```
 
-For a `<script>` tag drop-in (no bundler), use:
+For React/Vue/Solid hosts, call `init()` from a mount lifecycle hook
+(`useEffect`, `onMounted`, `onMount`) and call the returned `destroy` on
+cleanup. There's no framework-specific entrypoint — `init` is the entire
+public surface.
+
+For a `<script>` tag drop-in (no bundler), use the inline ESM form and **pin the version**:
+
+```html
+<script type="module">
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.3.0'
+
+  init({
+    apiUrl: '...',
+    apiKey: '...',
+    position: 'bottom-right',
+    theme: 'auto',
+  })
+</script>
+```
+
+If inline JS is disallowed (some CMS / page-builder editors), use the auto-init `<script src=…>` form with `data-*` attributes (`data-markup-widget="true"` is required):
 
 ```html
 <script
   type="module"
-  src="https://unpkg.com/@pixelmatters/markup"
+  src="https://esm.sh/@pixelmatters/markup@1.3.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."
@@ -178,8 +255,6 @@ For a `<script>` tag drop-in (no bundler), use:
 ></script>
 ```
 
-The `data-markup-widget="true"` attribute is required.
-
 ## Your task
 
 1. Detect my framework (React, Vue, Svelte, Next.js, plain HTML, etc.) by inspecting the project.
@@ -193,7 +268,7 @@ Constraints:
 
 - Do **not** add CSS imports or provider components — the widget needs neither.
 - Do **not** hardcode the key.
-- If the project has a CSP, add `https://unpkg.com` to `script-src` only if I'm using the `<script>` tag path.
+- If the project has a CSP, add `https://esm.sh` to `script-src` only if I'm using the `<script>` tag path.
 ````
 
 ## Browser support
@@ -204,7 +279,7 @@ Modern evergreen browsers (Chrome, Edge, Firefox, Safari) and their mobile equiv
 
 ```bash
 pnpm dev          # vite dev server with the playground page
-pnpm build        # production build → dist/{widget,react}.{js,d.ts}
+pnpm build        # production build → dist/widget.{js,d.ts}
 pnpm typecheck    # tsc --noEmit
 ```