@cohiva/support-widget 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# Cohiva Support Widget
+
+[![CI](https://github.com/cohiva/cohiva-support-widget/actions/workflows/ci.yml/badge.svg)](https://github.com/cohiva/cohiva-support-widget/actions/workflows/ci.yml)
+[![Release](https://github.com/cohiva/cohiva-support-widget/actions/workflows/release.yml/badge.svg)](https://github.com/cohiva/cohiva-support-widget/actions/workflows/release.yml)
+
+Shared, production-ready Support Ticket package for React apps. It preserves the documented legacy flow from the audit in `docs/support-widget-audit/` with a typed public API, diagnostics capture, and backend-compatible payload generation for `POST /api/feedback`.
+
+## What This Package Does
+
+This package provides a reusable support ticket widget that host apps can mount once and configure with app context, route metadata, auth, and API wiring. It standardizes:
+
+- floating launcher UX
+- two-step modal flow
+- type-aware validation and payload construction
+- diagnostics capture and redaction hooks
+- central API submission contract compatibility
+
+## What This Package Provides
+
+- Floating bottom-right Support Ticket launcher.
+- Two-step modal flow:
+  - type selection
+  - detailed form
+- Supported types:
+  - `bug`
+  - `feature`
+  - `feedback`
+  - `improvement`
+- Type-specific required validation rules with parity error messages.
+- Automatic diagnostics capture (actions, errors, page and runtime metadata).
+- Typed payload generation with backend-compatible keys.
+- Central API adapter (`createCentralFeedbackClient`).
+- Theme/class override surface.
+- Comprehensive test suite derived from migration checklist and parity requirements.
+
+## Install
+
+```bash
+npm install @cohiva/support-widget
+```
+
+Also include package CSS once in your app:
+
+```ts
+import '@cohiva/support-widget/styles.css';
+```
+
+## Quick Start
+
+```tsx
+import { SupportWidget } from '@cohiva/support-widget';
+
+export function App() {
+  return (
+    <SupportWidget
+      config={{
+        appName: 'Cohiva Admin',
+        environment: 'production',
+        repoSlug: 'cohiva/cohiva-admin',
+        apiBaseUrl: 'https://api.cohiva.app',
+        getAuthToken: () => localStorage.getItem('token'),
+        getCurrentRoute: () => ({
+          pathname: window.location.pathname,
+          href: window.location.href,
+          title: document.title,
+        }),
+        getCurrentUserContext: () => ({
+          user_id: 'u-123',
+          business_id: 'b-123',
+          role: 'admin',
+        }),
+      }}
+    />
+  );
+}
+```
+
+## Advanced Usage
+
+```tsx
+import { SupportWidget, createCentralFeedbackClient } from '@cohiva/support-widget';
+
+const submitFeedback = createCentralFeedbackClient({
+  apiBaseUrl: 'https://api.cohiva.app',
+  getAuthToken: () => window.sessionStorage.getItem('token'),
+});
+
+export function AppSupport() {
+  return (
+    <SupportWidget
+      config={{
+        appName: 'Cohiva Admin',
+        environment: 'production',
+        repoSlug: 'cohiva/cohiva-admin',
+        apiBaseUrl: 'https://api.cohiva.app',
+        getCurrentRoute: () => ({
+          pathname: window.location.pathname,
+          href: window.location.href,
+          title: document.title,
+        }),
+        getCurrentUserContext: () => ({
+          user_id: 'u-123',
+          business_id: 'b-456',
+          role: 'owner',
+        }),
+        diagnostics: {
+          captureConsoleWarnings: true,
+          clearPolicy: 'on_success',
+          redact: (entry) => {
+            if (entry.message.includes('password')) {
+              return null;
+            }
+            return {
+              ...entry,
+              message: entry.message.replace(/token=[^\s]+/g, 'token=[redacted]'),
+            };
+          },
+        },
+        theme: {
+          launcherLabel: 'Support Ticket',
+          classNames: {
+            launcher: 'my-app-launcher',
+            dialog: 'my-app-dialog',
+          },
+        },
+      }}
+      onSubmit={submitFeedback}
+      onSuccess={(result) => {
+        console.info('Support ticket submitted', result.feedback_id);
+      }}
+      onError={(error) => {
+        console.error('Support ticket failed', error);
+      }}
+    />
+  );
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run dev:example
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+npm run test:smoke
+npm run check
+```
+
+## Test Commands
+
+```bash
+npm run test:unit
+npm run test:component
+npm run test:smoke
+npm run test:coverage
+```
+
+## Release Workflow Summary
+
+This repository uses Changesets.
+
+1. Create a changeset for user-facing package changes:
+
+```bash
+npm run changeset
+```
+
+2. CI runs validation on PRs (`lint`, `typecheck`, `test`, `build`, example smoke build).
+3. On merge to `main`, the Changesets GitHub action either:
+  - opens/updates a release PR with version bumps and changelog updates, or
+  - publishes to npm when release changes are already prepared.
+
+Manual commands:
+
+```bash
+npm run version-packages
+npm run release
+```
+
+## Docs
+
+- `docs/public-api.md`
+- `docs/configuration.md`
+- `docs/diagnostics.md`
+- `docs/theming.md`
+- `docs/accessibility.md`
+- `docs/development.md`
+- `docs/testing.md`
+- `docs/releasing.md`
+- `docs/github-actions.md`
+- `docs/repo-secrets-and-publishing.md`
+- `docs/consuming-the-package.md`
+- `docs/migration-from-legacy-widget.md`
+- `docs/parity-matrix.md`
+- `docs/release-readiness-summary.md`
+- `docs/github-actions-setup-summary.md`
+
+## Node Version Note
+
+CI uses Node 20.x. Local development should use Node 20 for best parity with CI validation and release pipelines.
+
+## Source-of-Truth Requirement
+
+All implementation decisions in this package are derived from the audit documents under `docs/support-widget-audit/01-14`. If behavior needs to change, update the parity matrix and migration guide in the same change set.