@inputbuffer/feedback 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 inputbuffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,638 @@
+# @inputbuffer/feedback
+
+[InputBuffer](https://inputbuffer.io) is a feedback platform built for developer-facing products. It collects feedback from your users and uses AI-driven categorization to surface patterns.
+
+This package is a lightweight embeddable widget you can drop into your documentation sites, API and SDK references, CLI docs, or any other web property.
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+  - [Inline thumbs bar](#inline-thumbs-bar-web-component)
+  - [Thumbs only](#thumbs-only-web-component)
+  - [Floating thumbs bar](#floating-thumbs-bar-web-component)
+  - [Modal](#modal-script-tag)
+  - [Verify it's working](#verify-its-working)
+  - [Troubleshooting](#troubleshooting)
+- [Installation](#installation)
+  - [CDN](#cdn-recommended)
+  - [npm](#npm)
+  - [Browser support](#browser-support)
+- [Reference](#reference)
+- [Feedback bar](#feedback-bar)
+  - [Web component](#web-component)
+  - [`createBar(config)`](#inputbufferiocreatebarconfig)
+  - [`bar.on(event, handler)`](#baronevent-handler)
+  - [`bar.destroy()`](#bardestroy)
+- [Feedback modal](#feedback-modal)
+  - [Script tag attributes](#script-tag-attributes-auto-init)
+  - [`createModal(config)`](#inputbufferiocreatemodal config)
+  - [`instance.open(options?)`](#instanceopenoptions)
+  - [`instance.close()`](#instanceclose)
+  - [`instance.destroy()`](#instancedestroy)
+  - [`instance.on(event, handler)`](#instanceonevent-handler)
+  - [`InputBufferIO.version`](#inputbufferioversion)
+- [Target metadata schemas](#target-metadata-schemas)
+- [CSS customization](#css-customization)
+  - [Modal selectors](#modal-selectors)
+  - [Bar selectors](#bar-selectors)
+  - [CSS custom properties](#css-custom-properties)
+- [Common tasks](#common-tasks)
+- [License](#license)
+
+---
+
+## Quick start
+
+Before you start you will need a widget API key from your [InputBuffer dashboard](https://inputbuffer.io).
+
+There are three bundles — pick the one that matches your use case:
+
+| Bundle | Size | What it includes |
+|---|---|---|
+| `bar.js` | 18 KB | Thumbs up/down bar with optional follow-up form |
+| `modal.js` | 19 KB | Full-text feedback modal |
+| `widget.js` | 36 KB | Both bar and modal |
+
+### Inline thumbs bar (web component)
+
+The simplest way to add feedback. Drop the script tag anywhere in your page, then place the web component where you want the bar to appear:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+
+<inputbuffer-feedback
+  api-key="YOUR_WIDGET_TOKEN"
+  label="Was this helpful?">
+</inputbuffer-feedback>
+```
+
+The bar renders inline with thumbs up/down buttons. After a vote, a short follow-up form appears so the user can add context. On submit, the feedback is sent to InputBuffer.
+
+| Light | Dark |
+|---|---|
+| ![Bar light](example/bar-light.png) | ![Bar dark](example/bar-dark.png) |
+
+### Thumbs only (web component)
+
+Omit the `label` attribute to show just the thumbs with no text:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+
+<inputbuffer-feedback api-key="YOUR_WIDGET_TOKEN"></inputbuffer-feedback>
+```
+
+| Light | Dark |
+|---|---|
+| ![Thumbs light](example/thumbs-light.png) | ![Thumbs dark](example/thumbs-dark.png) |
+
+### Floating thumbs bar (web component)
+
+Add `placement="fixed"` to pin the bar to the bottom of the viewport — useful for documentation pages where you want persistent feedback access:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+
+<inputbuffer-feedback
+  api-key="YOUR_WIDGET_TOKEN"
+  label="Was this helpful?"
+  placement="fixed">
+</inputbuffer-feedback>
+```
+
+### Modal (script tag)
+
+If you want a full-text feedback modal triggered by a button, load `modal.js` with your API key and a CSS selector for the trigger element:
+
+| Light | Dark |
+|---|---|
+| ![Modal light](example/modal-light.png) | ![Modal dark](example/modal-dark.png) |
+
+```html
+<button id="feedback-btn">Send feedback</button>
+
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js"
+    data-api-key="YOUR_WIDGET_TOKEN"
+    data-attach-to="#feedback-btn">
+</script>
+```
+
+When the page loads the widget connects to `#feedback-btn`. Clicking it opens a modal with a text field and optional email field.
+
+### Verify it's working
+
+Submit a test message from your page and open your InputBuffer dashboard. It should appear in your feedback inbox within a few seconds, already categorized.
+
+### Troubleshooting
+
+- **Nothing happens on click:** check that the `data-attach-to` selector matches your button's `id` exactly, including the `#`.
+- **401 error:** your `data-api-key` is invalid — try again with a fresh copy from the dashboard, and if it still fails [contact us](https://inputbuffer.io/contact).
+
+### Where to go from here
+
+- Customize the bar with `label`, `placement`, and theme attributes (see [Web component](#web-component))
+- Create the bar programmatically with `createBar()` for full config access (see [`InputBufferIO.createBar(config)`](#inputbuffercreatebarconfig))
+- Listen for vote and submit events (see [`bar.on(event, handler)`](#baronevent-handler))
+
+---
+
+## Installation
+
+### CDN (recommended)
+
+Load only the component you need — each is roughly half the full bundle:
+
+```html
+<!-- Full bundle (modal + bar) — 36 KB -->
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/widget.js"
+    data-api-key="YOUR_WIDGET_TOKEN">
+</script>
+
+<!-- Modal only — 19 KB -->
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js"
+    data-api-key="YOUR_WIDGET_TOKEN">
+</script>
+
+<!-- Bar only — 18 KB -->
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+```
+
+> **SRI note:** For production deployments, add a Subresource Integrity `integrity` attribute to guard against CDN compromise. Generate the hash for each pinned version with:
+> ```bash
+> curl -s https://cdn.jsdelivr.net/npm/@inputbuffer/feedback@0.1.0/dist/widget.js | openssl dgst -sha384 -binary | openssl base64 -A
+> ```
+> Then use `integrity="sha384-<hash>" crossorigin="anonymous"` on the `<script>` tag.
+
+The stylesheet is injected automatically — no separate `<link>` tag needed. Pass `data-inject-styles="false"` to opt out and load `dist/modal.css` or `dist/bar.css` yourself.
+
+> **CSP note:** Style injection requires `style-src 'unsafe-inline'` in your Content Security Policy. If your CSP blocks inline styles, pass `data-inject-styles="false"` (or `injectStyles: false` in `createModal()`) and load the stylesheet manually via `<link>` instead.
+
+### npm
+
+```bash
+npm install @inputbuffer/feedback
+```
+
+Import only what you use — your bundler will tree-shake the rest:
+
+```js
+// Modal only (~19 KB unminified)
+import { createModal } from '@inputbuffer/feedback/modal';
+
+// Bar only (~18 KB unminified)
+import { createBar } from '@inputbuffer/feedback/bar';
+
+// Full bundle
+import { InputBufferIO } from '@inputbuffer/feedback';
+```
+
+TypeScript types are included and exported from each entry point.
+
+### Browser support
+
+Chrome 111+, Firefox 113+, Safari 16.2+. The bundles target ES2019 and rely on Custom Elements v1 (used by the `<inputbuffer-feedback>` web component).
+
+---
+
+## Reference
+
+Each CDN bundle sets `window.InputBufferIO` at parse time — no `DOMContentLoaded` needed. What's exposed depends on which bundle you load:
+
+| Bundle | `window.InputBufferIO` |
+|---|---|
+| `widget.js` | `{ createModal, createBar, version }` |
+| `modal.js` | `{ createModal, version }` |
+| `bar.js` | `{ createBar, version }` |
+
+When using npm imports, use the named exports directly (`createModal`, `createBar`) rather than the global.
+
+---
+
+## Feedback bar
+
+The feedback bar is an inline or fixed thumbs up/down component — a lightweight alternative to the modal. It can be used as a web component or created programmatically.
+
+### Web component
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+
+<inputbuffer-feedback api-key="YOUR_WIDGET_TOKEN" label="Was this helpful?"></inputbuffer-feedback>
+```
+
+Supported attributes:
+
+| Attribute | Description |
+|---|---|
+| `api-key` | **Required.** Your widget API key. |
+| `api-url` | Override the API endpoint. |
+| `label` | Text shown next to the thumbs. |
+| `placement` | `"inline"` (default) or `"fixed"` (pins to bottom of viewport). |
+| `theme-primary` | Primary color. |
+| `theme-background` | Background color. |
+| `theme-text` | Text color. |
+| `theme-selected` | Background color of the selected thumb. |
+| `theme-selected-color` | Icon color of the selected thumb. |
+| `inject-styles` | Set to `"false"` to skip automatic style injection. |
+
+> **Note:** `colorScheme`, `showLabel`, `modalTitle`, `modalPlaceholder`, `showTitleField`, `showEmailField`, and `source` are not available as web component attributes. Use `InputBufferIO.createBar(config)` for those options.
+
+### `InputBufferIO.createBar(config)`
+
+Creates a feedback bar programmatically and returns a `FeedbackBarInstance` with an `element` property (mount it yourself) and a `destroy()` method.
+
+```js
+const bar = InputBufferIO.createBar({
+    apiKey: 'YOUR_WIDGET_TOKEN',
+    label: 'Was this helpful?',
+});
+document.getElementById('my-slot').appendChild(bar.element);
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | string | — | **Required.** Your widget API key. |
+| `apiUrl` | string | — | Override the API endpoint. |
+| `label` | string | — | Text shown next to the thumbs. |
+| `showLabel` | boolean | `true` | Set to `false` to show thumbs only. |
+| `placement` | `'inline'` \| `'fixed'` | `'inline'` | `fixed` pins the bar to the bottom of the viewport. |
+| `colorScheme` | `'light'` \| `'dark'` \| `'auto'` | `'auto'` | Force a color scheme or follow the system setting. |
+| `theme.primary` | string | — | Primary color (buttons, focus rings). |
+| `theme.background` | string | — | Bar and popover background color. |
+| `theme.surface` | string | — | Popover header surface color. |
+| `theme.text` | string | — | Text color. |
+| `theme.selected` | string | — | Background color of the selected thumb. |
+| `theme.selectedColor` | string | — | Icon color of the selected thumb. |
+| `target.type` | `'documentation'` \| `'rest_endpoint'` \| `'cli_command'` | — | The kind of thing the user is giving feedback on. Used for AI categorization. |
+| `target.targetId` | string | — | Optional stable ID for this target (used for deduplication on the server). |
+| `target.displayName` | string | — | Human-readable name shown in the InputBuffer dashboard (max 500 chars). |
+| `target.dedupKey` | string | — | Custom deduplication key (max 500 chars). |
+| `target.metadata` | object | — | Type-specific fields — see [Target metadata schemas](#target-metadata-schemas). |
+| `modalTitle` | string | — | Heading for the follow-up popover. |
+| `modalPlaceholder` | string | — | Textarea placeholder for the follow-up popover. |
+| `showEmailField` | boolean | `false` | Show/hide the email field in the follow-up popover. |
+| `showTitleField` | boolean | `false` | Show/hide the title field in the follow-up popover. |
+| `source` | string | — | Tag identifying which of your surfaces this widget is embedded on (e.g. `"ios-app"`, `"docs-site"`). Stored on every submission for filtering in the dashboard. |
+| `injectStyles` | boolean | `true` | Set to `false` to skip automatic style injection. |
+
+### `bar.on(event, handler)`
+
+Subscribes to bar lifecycle events.
+
+```js
+bar.on('vote',   ({ sentiment }) => console.log('Voted:', sentiment));
+bar.on('open',   ({ sentiment }) => console.log('Popover opened after:', sentiment));
+bar.on('submit', ({ id })        => console.log('Feedback ID:', id));
+bar.on('close',  ()              => console.log('Popover closed'));
+bar.on('error',  (err)           => console.error('Submission failed:', err));
+```
+
+| Event | Handler signature | When it fires |
+|---|---|---|
+| `vote` | `({ sentiment: 'positive' \| 'negative' }) => void` | User clicks a thumb before submitting. |
+| `open` | `({ sentiment: 'positive' \| 'negative' }) => void` | The follow-up popover opens. |
+| `submit` | `({ id: string }) => void` | Feedback was submitted successfully. |
+| `close` | `() => void` | The follow-up popover closes. |
+| `error` | `(err: Error) => void` | The submission request failed. |
+
+### `bar.destroy()`
+
+Removes the bar element and all event listeners.
+
+---
+
+## Feedback modal
+
+The feedback modal is a full-text input form triggered by a button click. It can be opened programmatically or auto-initialized from the script tag.
+
+### Script tag attributes (auto-init)
+
+When `data-api-key` is present on the script tag, the widget initializes automatically. All config is read from `data-*` attributes.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `data-api-key` | string | **Required.** Your widget API key. |
+| `data-api-url` | string | Override the API endpoint (useful for local dev/testing). |
+| `data-attach-to` | string | CSS selector for the element that opens the modal on click. |
+| `data-inject-styles` | boolean | Set to `"false"` to skip automatic style injection. |
+| `data-color-scheme` | string | `"light"`, `"dark"`, or `"auto"`. |
+| `data-theme-primary` | string | Primary color (buttons, focus rings). Any CSS color value. |
+| `data-theme-background` | string | Modal background color. |
+| `data-theme-text` | string | Modal text color. |
+| `data-theme-selected` | string | Background color of the selected sentiment thumb. |
+| `data-theme-selected-color` | string | Icon color of the selected sentiment thumb. |
+
+> **Note:** `theme.surface` is only available via the programmatic API (`createModal(config)`), not as a `data-*` attribute.
+
+### `InputBufferIO.createModal(config)`
+
+Creates a widget instance programmatically. Returns a `WidgetInstance`.
+
+```js
+const ib = InputBufferIO.createModal({
+    apiKey: 'YOUR_WIDGET_TOKEN',
+});
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | string | — | **Required.** Your widget API key. |
+| `apiUrl` | string | — | Override the API endpoint (useful for local dev/testing). |
+| `attachTo` | string | — | CSS selector. Clicking the matched element calls `open()`. |
+| `injectStyles` | boolean | `true` | Set to `false` to skip automatic style injection. |
+| `title` | string | — | Modal heading. Omit to render no title. |
+| `placeholder` | string | `"What's on your mind?"` | Textarea placeholder text. |
+| `showEmailField` | boolean | `false` | Set to `true` to show an optional email field. |
+| `showTitleField` | boolean | `false` | Set to `true` to show an optional title field. |
+| `showSentiment` | boolean | `false` | Show thumbs up/down sentiment buttons in the modal. |
+| `source` | string | — | Tag identifying which of your surfaces this widget is embedded on (e.g. `"ios-app"`, `"docs-site"`). Stored on every submission for filtering in the dashboard. |
+| `colorScheme` | `'light'` \| `'dark'` \| `'auto'` | `'auto'` | Force a color scheme or follow the system setting. |
+| `theme.primary` | string | — | Primary color (buttons, focus rings). |
+| `theme.background` | string | — | Modal background color. |
+| `theme.surface` | string | — | Modal header surface color. |
+| `theme.text` | string | — | Modal text color. |
+| `theme.selected` | string | — | Background color of the selected sentiment thumb. |
+| `theme.selectedColor` | string | — | Icon color of the selected sentiment thumb. |
+
+### `instance.open(options?)`
+
+Opens the feedback modal. Pass options to provide context at call time — useful when the same widget instance is reused across different pages or sections.
+
+```js
+ib.open({
+    title: 'Was this helpful?',
+    target: {
+        type: 'documentation',
+        targetId: 'auth-overview',
+        displayName: 'Authentication overview',
+        metadata: {
+            page_url: window.location.href,
+            section_heading: 'Authentication',
+        },
+    },
+    prefill: {
+        description: '👍 This page was helpful',
+    },
+});
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `title` | string | Overrides the modal heading for this open call. |
+| `sentiment` | `'positive'` \| `'negative'` | Pre-selects a sentiment thumb. Only relevant when `showSentiment` is enabled. |
+| `target.type` | `'documentation'` \| `'rest_endpoint'` \| `'cli_command'` | The kind of thing the user is giving feedback on. Used for AI categorization. |
+| `target.targetId` | string | Optional stable ID for this target (used for deduplication on the server). |
+| `target.displayName` | string | Human-readable name shown in the InputBuffer dashboard (max 500 chars). |
+| `target.dedupKey` | string | Custom deduplication key (max 500 chars). |
+| `target.metadata` | object | Type-specific fields — see [Target metadata schemas](#target-metadata-schemas). |
+| `prefill.email` | string | Pre-populates the email field. |
+| `prefill.description` | string | Pre-populates the textarea. |
+| `source` | string | Overrides the `source` set in `createModal(config)` for this open call. |
+
+### `instance.close()`
+
+Closes the modal programmatically.
+
+### `instance.destroy()`
+
+Closes the modal and removes all event listeners and DOM elements. The instance cannot be reused after this call — invoke `createModal()` again to get a fresh one. You may have multiple `WidgetInstance`s on a page, but opening more than one modal simultaneously is not supported (they share DOM IDs).
+
+### `instance.on(event, handler)`
+
+Subscribes to widget lifecycle events.
+
+```js
+ib.on('submit', (result) => console.log('Feedback ID:', result.id));
+ib.on('close',  ()       => console.log('Modal closed'));
+ib.on('error',  (err)    => console.error('Submission failed:', err));
+```
+
+| Event | Handler signature | When it fires |
+|---|---|---|
+| `submit` | `(result: { id: string }) => void` | Feedback was submitted successfully. `result.id` is the InputBuffer feedback ID. |
+| `close` | `() => void` | The modal was closed, either by the user or programmatically. |
+| `error` | `(err: Error) => void` | The submission request failed. |
+
+### `InputBufferIO.version`
+
+The currently loaded widget version string.
+
+```js
+console.log(InputBufferIO.version); // e.g. "0.1.0"
+```
+
+### Target metadata schemas
+
+The fields accepted in `target.metadata` depend on `target.type`. The server validates required fields; the client does not enforce them.
+
+**`documentation`**
+
+| Field | Required | Description |
+|---|---|---|
+| `page_url` | No | Full URL of the page. |
+| `page_slug` | No | Slug or path of the page. |
+| `section_heading` | No | Heading of the section the user is viewing. |
+| `doc_version` | No | Documentation version string. |
+
+**`rest_endpoint`**
+
+| Field | Required | Description |
+|---|---|---|
+| `method` | Yes* | HTTP method (`GET`, `POST`, etc.). |
+| `path` | Yes* | API path (e.g. `/v1/users`). |
+| `host` | No | Hostname (e.g. `api.example.com`). |
+| `api_version` | No | API version string. |
+
+**`cli_command`**
+
+| Field | Required | Description |
+|---|---|---|
+| `command` | Yes* | Top-level CLI command (e.g. `auth`). |
+| `subcommand` | No | Subcommand (e.g. `setup`). |
+| `cli_version` | No | CLI version string. |
+
+\* Required by the server; omitting them will result in a validation error response.
+
+---
+
+## CSS customization
+
+Each component uses stable selectors you can target directly in your stylesheet.
+
+### Modal selectors
+
+| Selector | Class alias | Element |
+|---|---|---|
+| `#ib-overlay` | — | Full-screen backdrop |
+| `#ib-modal` | — | Modal container (scopes all CSS variables) |
+| `#ib-modal-header` | — | Header bar |
+| `#ib-modal-body` | — | Body area |
+| `#ib-title` | `.ib-modal-title` | Modal heading |
+| `#ib-textarea` | `.ib-modal-textarea` | Feedback text field |
+| `#ib-email` | `.ib-modal-email` | Email input |
+| `#ib-submit` | `.ib-modal-submit` | Submit button |
+| `#ib-close` | `.ib-modal-close` | Close button |
+| `#ib-success` | `.ib-modal-success` | Success message |
+| `#ib-error` | `.ib-modal-error` | Error message |
+
+The IDs are the stable public API and will not change between releases. The `.ib-modal-*` class aliases are equivalent and exist for symmetry with the bar.
+
+### Bar selectors
+
+| Class | Element |
+|---|---|
+| `.ib-bar-wrapper` | Outer wrapper (scopes all CSS variables) |
+| `.ib-bar` | The visible bar strip |
+| `.ib-bar-label` | Label text |
+| `.ib-bar-btn` | Thumb buttons |
+| `.ib-bar-popover` | Follow-up popover container |
+| `.ib-bar-header` | Popover header |
+| `.ib-bar-body` | Popover body |
+| `.ib-bar-title` | Popover heading |
+| `.ib-bar-textarea` | Feedback text field |
+| `.ib-bar-email` | Email input |
+| `.ib-bar-submit` | Submit button |
+| `.ib-bar-success` | Success message |
+| `.ib-bar-error` | Error message |
+
+### CSS custom properties
+
+Both components expose the same set of CSS custom properties. Set them on `#ib-modal` or `.ib-bar-wrapper` respectively, or pass them via the `theme` config option.
+
+| Property | Default (light) | Default (dark) | What it affects |
+|---|---|---|---|
+| `--ib-primary` | `#6366f1` | `#3A5244` | Buttons, focus rings, borders |
+| `--ib-primary-hover` | `#4338ca` | `#4E6857` | Button hover state |
+| `--ib-background` | `#f6f6f8` | `#25272B` | Form area background |
+| `--ib-surface` | `#ffffff` | `#2C3630` | Header/card background |
+| `--ib-text` | `#111827` | `#E5E7EB` | Body text |
+| `--ib-muted` | `#8d99ae` | `#9CA3AF` | Label and hint text |
+| `--ib-border` | `(primary)` | `#363840` | Border color |
+| `--ib-selected` | `(primary)` | `(primary)` | Selected thumb background |
+| `--ib-selected-color` | `(surface)` | `(surface)` | Selected thumb icon color |
+| `--ib-radius` | `2px` | `8px` | Container border radius |
+| `--ib-radius-input` | `2px` | `4px` | Input/button border radius |
+
+---
+
+## Common tasks
+
+### Attach feedback to a specific docs page
+
+```js
+// <script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js" data-api-key="YOUR_WIDGET_TOKEN"></script>
+const ib = InputBufferIO.createModal({ apiKey: 'YOUR_WIDGET_TOKEN' });
+
+document.getElementById('feedback-btn').addEventListener('click', () => {
+    ib.open({
+        title: 'Was this page helpful?',
+        target: {
+            type: 'documentation',
+            targetId: window.location.pathname,
+            displayName: document.title,
+            metadata: {
+                page_url: window.location.href,
+                section_heading: document.querySelector('h1')?.textContent ?? '',
+            },
+        },
+    });
+});
+```
+
+### Attach feedback to a REST endpoint reference
+
+```js
+// <script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js" data-api-key="YOUR_WIDGET_TOKEN"></script>
+const ib = InputBufferIO.createModal({ apiKey: 'YOUR_WIDGET_TOKEN' });
+
+ib.open({
+    target: {
+        type: 'rest_endpoint',
+        targetId: 'POST /v1/uploads',
+        displayName: 'Upload a file',
+        metadata: { method: 'POST', path: '/v1/uploads' },
+    },
+});
+```
+
+### Attach feedback to a CLI command reference
+
+```js
+// <script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js" data-api-key="YOUR_WIDGET_TOKEN"></script>
+const ib = InputBufferIO.createModal({ apiKey: 'YOUR_WIDGET_TOKEN' });
+
+ib.open({
+    target: {
+        type: 'cli_command',
+        targetId: 'deploy',
+        displayName: 'my-cli deploy',
+        metadata: { command: 'deploy' },
+    },
+});
+```
+
+### Listen for submissions
+
+```js
+// <script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js" data-api-key="YOUR_WIDGET_TOKEN"></script>
+const ib = InputBufferIO.createModal({ apiKey: 'YOUR_WIDGET_TOKEN' });
+
+ib.on('submit', ({ id }) => {
+    analytics.track('feedback_submitted', { feedbackId: id });
+});
+
+ib.on('error', (err) => {
+    console.error('Feedback submission failed:', err.message);
+});
+```
+
+### Force a dark theme
+
+```js
+// <script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js" data-api-key="YOUR_WIDGET_TOKEN"></script>
+InputBufferIO.createModal({
+    apiKey: 'YOUR_WIDGET_TOKEN',
+    colorScheme: 'dark',
+    theme: {
+        primary: '#818cf8',
+        background: '#1e1e2e',
+        text: '#cdd6f4',
+    },
+}).open();
+```
+
+### Add a thumbs bar to a docs page
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/bar.js"></script>
+
+<inputbuffer-feedback api-key="YOUR_WIDGET_TOKEN" label="Was this helpful?"></inputbuffer-feedback>
+```
+
+### Load only the bar via npm
+
+```js
+import { createBar } from '@inputbuffer/feedback/bar';
+
+const bar = createBar({ apiKey: 'YOUR_WIDGET_TOKEN', label: 'Was this helpful?' });
+document.getElementById('my-slot').appendChild(bar.element);
+```
+
+### Load your own CSS instead of the injected styles
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.css">
+
+<script src="https://cdn.jsdelivr.net/npm/@inputbuffer/feedback/dist/modal.js"
+    data-api-key="YOUR_WIDGET_TOKEN"
+    data-inject-styles="false">
+</script>
+```
+
+---
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,5 @@
+import type { OpenOptions } from './types.js';
+export declare const WIDGET_VERSION: string;
+export declare function submitFeedback(apiKey: string, description: string, email: string | null, title: string | null, options?: OpenOptions, apiUrl?: string): Promise<{
+    id: string;
+}>;

package/dist/bar-entry.d.ts

@@ -0,0 +1,8 @@
+import type { FeedbackBarConfig, FeedbackBarInstance } from './types.js';
+declare function createBar(config: FeedbackBarConfig): FeedbackBarInstance;
+declare const InputBufferIO: {
+    createBar: typeof createBar;
+    version: string;
+};
+export type { FeedbackBarConfig, FeedbackBarInstance };
+export { InputBufferIO, createBar };

package/dist/bar.css

@@ -0,0 +1 @@
+.ib-bar-wrapper{--ib-primary: #6366f1;--ib-primary-hover: #4338ca;--ib-background: #f6f6f8;--ib-surface: #ffffff;--ib-text: #111827;--ib-muted: #8d99ae;--ib-border: var(--ib-primary);--ib-focus-color: var(--ib-primary);--ib-input-hover-border: var(--ib-border);--ib-selected: var(--ib-primary);--ib-selected-color: var(--ib-surface);--ib-radius: 2px;--ib-radius-input: 2px;position:relative;display:inline-block;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif}.ib-bar-wrapper--fixed{position:fixed;bottom:32px;right:32px;z-index:9998}.ib-bar{display:inline-flex;align-items:stretch;height:40px;width:100%;overflow:hidden;background-color:var(--ib-background);border:1px solid var(--ib-border);border-radius:2px;box-shadow:0 1px 4px #00000014;box-sizing:border-box}.ib-bar-popover{display:none;position:absolute;bottom:calc(100% + 8px);right:0;width:320px;border:1px solid var(--ib-border);border-radius:var(--ib-radius);box-shadow:0 1px 3px #0000001f;box-sizing:border-box;z-index:9999;overflow:hidden}.ib-bar-popover--visible{display:block}.ib-bar-header{background:var(--ib-surface);padding:12px 16px;border-bottom:1px solid var(--ib-border)}.ib-bar-body{background:var(--ib-background);padding:16px}.ib-bar-title{font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.1em;color:var(--ib-text);margin:0}.ib-bar-textarea{width:100%;background:var(--ib-background);border:1px solid var(--ib-border);border-radius:var(--ib-radius-input);padding:10px 12px;font-size:14px;font-family:inherit;color:var(--ib-text);resize:vertical;min-height:80px;box-sizing:border-box;outline:none;display:block}.ib-bar-textarea:hover{border-color:var(--ib-input-hover-border)}.ib-bar-textarea:focus{border-color:var(--ib-focus-color);box-shadow:0 0 0 2px color-mix(in srgb,var(--ib-focus-color) 15%,transparent)}.ib-bar-wrapper .ib-bar-body .ib-bar-title-input,.ib-bar-wrapper .ib-bar-body .ib-bar-email{width:100%;background:var(--ib-background);border:1px solid var(--ib-border);border-radius:var(--ib-radius-input);padding:8px 12px;font-size:14px;font-family:inherit;color:var(--ib-text);box-sizing:border-box;outline:none;display:block}.ib-bar-title-input{margin-bottom:8px}.ib-bar-email{margin-top:8px}.ib-bar-wrapper .ib-bar-body .ib-bar-title-input:hover,.ib-bar-wrapper .ib-bar-body .ib-bar-email:hover{border-color:var(--ib-input-hover-border)}.ib-bar-wrapper .ib-bar-body .ib-bar-title-input:focus,.ib-bar-wrapper .ib-bar-body .ib-bar-email:focus{border-color:var(--ib-focus-color);box-shadow:0 0 0 2px color-mix(in srgb,var(--ib-focus-color) 15%,transparent)}.ib-bar-submit{background:var(--ib-primary);color:#fff;border:none;border-radius:var(--ib-radius-input);padding:8px 16px;font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.08em;font-family:inherit;cursor:pointer;display:inline-block;transition:background .15s}.ib-bar-submit:hover{background:var(--ib-primary-hover)}.ib-bar-submit:disabled{opacity:.6;cursor:not-allowed}.ib-bar-footer{display:flex;align-items:center;justify-content:space-between;margin-top:10px}.ib-branding a{font-size:10px;color:var(--ib-muted);text-decoration:none;letter-spacing:.03em}.ib-branding a:hover{color:var(--ib-primary);text-decoration:underline}.ib-bar-error,.ib-bar-success{font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.08em;margin:8px 0 0}.ib-bar-error:empty,.ib-bar-success:empty{display:none}.ib-bar-error{color:#dc2626}.ib-bar-success{color:#16a34a}.ib-bar-label-area{flex:1;display:flex;align-items:center;padding:0 16px}.ib-bar-label{font-size:11px;font-weight:600;color:var(--ib-muted);text-transform:uppercase;letter-spacing:.1em;white-space:nowrap;user-select:none}.ib-bar-actions{display:flex;align-items:stretch;background:var(--ib-background);border-left:1px solid var(--ib-border)}.ib-bar-actions--no-label{border-left:none}.ib-bar-btn{width:40px;display:flex;align-items:center;justify-content:center;background:var(--ib-background);border:none;border-right:1px solid var(--ib-border);border-radius:0;color:var(--ib-primary);cursor:pointer;transition:background .15s,color .15s,transform .1s;padding:0;-webkit-appearance:none;appearance:none;box-sizing:border-box;margin:0}.ib-bar-btn--down{border-right:none}.ib-bar-btn:hover{background:var(--ib-primary);color:var(--ib-surface);transform:scale(1.15)}.ib-bar-btn:active{transform:scale(.95)}.ib-bar-btn:focus{outline:1px solid var(--ib-primary);outline-offset:-1px}.ib-bar-btn--active{background:var(--ib-selected);color:var(--ib-selected-color)}.ib-bar-btn--active:hover{background:var(--ib-primary-hover, var(--ib-primary));color:var(--ib-surface);transform:scale(1.1)}@media (prefers-color-scheme: dark){.ib-bar-wrapper:not(.ib-theme-light),.ib-bar-wrapper.ib-theme-dark{--ib-primary: #3A5244;--ib-primary-hover: #4E6857;--ib-background: #25272B;--ib-surface: #2C3630;--ib-text: #E5E7EB;--ib-muted: #9CA3AF;--ib-border: #363840;--ib-focus-color: #7B9B82;--ib-input-hover-border: rgba(255, 255, 255, .2);--ib-selected: #7B9B82;--ib-selected-color: #1a2420;--ib-radius: 8px;--ib-radius-input: 4px}}.ib-bar-wrapper.ib-theme-dark{--ib-primary: #3A5244;--ib-primary-hover: #4E6857;--ib-background: #25272B;--ib-surface: #2C3630;--ib-text: #E5E7EB;--ib-muted: #9CA3AF;--ib-border: #363840;--ib-focus-color: #7B9B82;--ib-input-hover-border: rgba(255, 255, 255, .2);--ib-selected: #7B9B82;--ib-selected-color: #1a2420;--ib-radius: 8px;--ib-radius-input: 4px}