@getpinax/widget 0.0.0-stage → 1.0.0-beta.2

package/dist/types.d.ts

@@ -0,0 +1,247 @@
+export type PinaxOptions = {
+    /** The website's public key (S-08). */
+    key: string;
+    /** Override the API origin, e.g. for local development. */
+    apiUrl?: string;
+    /** Segment: force sending events to `window.analytics` on or off, whatever the site's setting. */
+    segment?: boolean;
+    /**
+     * Override the CDN origin that serves the site's settings (P-15), default
+     * https://cdn.getpinax.com. When `apiUrl` is set and this isn't, settings
+     * come from the API.
+     */
+    cdnUrl?: string;
+    /**
+     * Visitor consent: `'wait'` holds replay, technical logs, error counts
+     * and the page-view count until `consent()` says yes; `'none'` never
+     * waits. Without it the site's setting (`settings.consent.required`)
+     * decides. `data-consent` on the script tag.
+     */
+    consent?: 'wait' | 'none';
+};
+/**
+ * Visitor consent, from the site's cookie banner: `true` or `false` for
+ * everything, or only the parts given. `diagnostics` covers technical logs
+ * on reports, fix checks, error counts (with the basket), the Segment user id
+ * and the page-view count; `replay` the session recorder.
+ */
+export type PinaxConsent = boolean | {
+    diagnostics?: boolean;
+    replay?: boolean;
+};
+/**
+ * Signed-in visitor details (C-09). `id` and `name` go with reports; `email`
+ * only fills in the form's email box (when the site allows it) and is sent
+ * only if the visitor leaves it there.
+ */
+export type PinaxUser = {
+    id?: string;
+    name?: string;
+    email?: string;
+};
+/**
+ * AI-21: what the visitor has in their basket right now, in major units
+ * (19.99, not 1999) and an ISO 4217 code. Sent only with a sampled
+ * sighting of an open report's error (P-17), never on its own.
+ */
+export type PinaxBasket = {
+    value: number;
+    currency: string;
+};
+export type WidgetPosition = 'bottom-right' | 'bottom-left' | 'right-edge';
+/** S-06: custom wording. An empty string means "use the default wording". */
+export type WidgetWording = {
+    chooserTitle: string;
+    problemTitle: string;
+    ideaTitle: string;
+    generalTitle: string;
+    /** W-19 */
+    accessibilityTitle: string;
+    messagePlaceholder: string;
+    confirmation: string;
+};
+/** W-10: an owner-defined field in the form. */
+export type CustomField = {
+    id: string;
+    type: 'select' | 'text' | 'checkbox';
+    label: string;
+    required: boolean;
+    /** Dropdown choices. */
+    options: string[];
+    /** Which kinds of feedback show it. */
+    types: {
+        problem: boolean;
+        idea: boolean;
+        general: boolean;
+    };
+};
+/** W-10: a visitor's answer, as sent in the report body. */
+export type FieldAnswer = {
+    id: string;
+    value: string | boolean;
+};
+/**
+ * The website's widget settings, as defined by
+ * `backend/src/modules/widget/widget-settings.ts`.
+ */
+export type WidgetSettings = {
+    /** S-01 */
+    color: string;
+    text: string;
+    position: WidgetPosition;
+    /** S-02; W-19 `accessibility` is off unless the owner switches it on. */
+    types: {
+        problem: boolean;
+        idea: boolean;
+        general: boolean;
+        accessibility: boolean;
+    };
+    rating: boolean;
+    /** S-04: path patterns where the button is hidden; `*` matches anything. */
+    hidePaths: string[];
+    /** S-04: a smaller button on phones. */
+    smallOnMobile: boolean;
+    /** S-05: no floating button; the site opens the widget with `Pinax.open()`. */
+    hideButton: boolean;
+    /** Segment: send widget events to the page's own `window.analytics`. */
+    segment: boolean;
+    /** S-06 */
+    wording: WidgetWording;
+    /** W-10 */
+    fields: CustomField[];
+    /** C-10: what is recorded with each report. */
+    capture: {
+        console: boolean;
+        network: boolean;
+    };
+    /**
+     * Known issues: show the "We know about this" card, and offer "Email me
+     * when it's fixed". Missing (older API) means both on, as the backend's
+     * defaults; with no `known` list in the config there's nothing to show.
+     */
+    knownIssues?: {
+        enabled: boolean;
+        notify: boolean;
+    };
+    /**
+     * Visitor consent: the site has a cookie banner, so replay, technical
+     * logs, error counts and the page-view count wait for `Pinax.consent()`.
+     * Missing (older API) means not required.
+     */
+    consent?: {
+        required: boolean;
+    };
+    /** The site's privacy policy (https), linked under the form; `''` = none. */
+    privacyUrl?: string;
+    /**
+     * Whether `identify()`'s email fills in the form's email box (the visitor
+     * can clear it). Missing (older API) means yes, as before.
+     */
+    identifyPrefill?: boolean;
+};
+/**
+ * W-17: "Powered by Pinax" (Starter) and, with client branding (Agency),
+ * the client's logo and colours. Missing or null = Pinax's own look.
+ */
+export type Branding = {
+    poweredBy: boolean;
+    logoUrl?: string | null;
+    primary?: string | null;
+    accent?: string | null;
+};
+/** AI-17: a report marked Fixed whose error the widget watches for. */
+export type FixCheck = {
+    id: string;
+    path: string;
+    signature: string;
+};
+/** AI-20: an open report whose error the widget counts on any page. */
+export type ErrorWatch = {
+    id: string;
+    signature: string;
+};
+/**
+ * Pinax AI switches for the browser (`widgetAiConfig` in
+ * `backend/src/modules/widget/widget.service.ts`).
+ */
+export type AiConfig = {
+    /** AI-10: ask one follow-up question about a short note. */
+    followUp: boolean;
+    /** AI-12: blur emails, phone numbers and names in screenshots. */
+    autoBlur: boolean;
+    /** AI-15 / P-13: keep a rolling 30-second replay (Pro and Agency). */
+    replay: boolean;
+    replaySampleRate: number;
+    /**
+     * What the recorder hides: `'all'` (the default) every text and every
+     * image, video, canvas and frame; `'inputs'` form fields, editable text,
+     * emails and phone numbers.
+     */
+    replayMask: 'all' | 'inputs';
+    /** AI-17 / P-14 */
+    fixChecks: FixCheck[];
+    /** AI-20 / P-17: open reports' errors, counted when seen; same sample rate as fix checks. */
+    watches: ErrorWatch[];
+    fixCheckSampleRate: number;
+};
+/**
+ * An open report the team chose to show to visitors, with a public title
+ * they wrote (never the visitor's own words).
+ */
+export type KnownIssue = {
+    id: string;
+    title: string;
+    /** Pages it was reported on; `/a` and `/a/` are the same page. */
+    paths: string[];
+    /** Its error signature (`errorSignature`), when it has one. */
+    signature: string | null;
+};
+/** `data` of GET /v1/widget/:key/config. */
+export type WidgetConfig = {
+    enabled: boolean;
+    /** S-15: hostnames that may send reports. Missing (older API) means don't check. */
+    allowedDomains?: string[];
+    settings: WidgetSettings;
+    branding: Branding;
+    /** B-17: over the limit, replay and fix-check sampling is cut (to 0.01). */
+    samplingRate?: number | null;
+    ai?: AiConfig;
+    /** Known issues for this site (up to 20). Missing (older API) means none. */
+    known?: KnownIssue[];
+};
+export type ReportType = 'PROBLEM' | 'IDEA' | 'GENERAL' | 'ACCESSIBILITY';
+/** W-19: what kind of barrier the visitor met (optional). */
+export type Barrier = 'see' | 'keyboard' | 'screen-reader' | 'media' | 'other';
+/** W-20: one failed axe-core rule. */
+export type A11yIssue = {
+    rule: string;
+    impact: 'minor' | 'moderate' | 'serious' | 'critical' | null;
+    help: string;
+    helpUrl: string;
+    /** WCAG success criteria, e.g. "1.4.3". */
+    wcag: string[];
+    /** How many elements fail it; `nodes` holds the first few. */
+    count: number;
+    nodes: {
+        target: string;
+        html: string;
+        summary: string;
+    }[];
+};
+/** W-20: the automatic scan sent with an accessibility report. */
+export type A11yScan = {
+    engine: string;
+    durationMs: number;
+    violations: A11yIssue[];
+    /** Rules that needed a person to check (not failures). */
+    incomplete: number;
+};
+/** One drawn mark, coordinates as fractions (0 to 1) of the sent image. */
+export type Annotation = {
+    type: 'box' | 'arrow' | 'text' | 'blur';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text?: string;
+};

package/dist/ui/color.d.ts

@@ -0,0 +1,7 @@
+/** Relative luminance of a #rgb or #rrggbb colour (WCAG 2). */
+export declare function luminance(hex: string): number | null;
+export declare function contrast(a: number, b: number): number;
+/** The board's dark ink (#0B1300) or white, whichever reads better on `bg`. */
+export declare function inkFor(bg: string): string;
+/** Only accept plain hex colours from config, so nothing odd reaches CSS. */
+export declare function safeColor(value: unknown, fallback?: string): string;

package/dist/ui/dom.d.ts

@@ -0,0 +1,14 @@
+type Attrs = Record<string, string | number | boolean | undefined | null>;
+type Child = Node | string | null | undefined | false;
+/** Tiny element builder. Text is always set as text, never parsed as HTML. */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Attrs, ...children: Child[]): HTMLElementTagNameMap[K];
+/** A 16px stroked icon from a path. */
+export declare function icon(d: string, size?: number): SVGSVGElement;
+export declare const ICONS: {
+    close: string;
+    back: string;
+    pen: string;
+    camera: string;
+    trash: string;
+};
+export {};

package/dist/ui/styles.d.ts

@@ -0,0 +1,3 @@
+/** The phone rules inside `open` (a media query or ''), `$` replaced by `wrap`. */
+export declare function phoneRules(open: string, wrap: string): string;
+export declare const CSS: string;

package/dist/ui/widget.d.ts

@@ -0,0 +1,241 @@
+import type { Annotation, Barrier, FieldAnswer, KnownIssue, PinaxUser, ReportType, WidgetConfig } from '../types';
+export type Shot = {
+    /** The flattened image that will be sent. */
+    dataUrl: string;
+    annotations: Annotation[];
+    /** Opaque editor state so "Mark up" can continue where it left off. */
+    edit?: unknown;
+    /** AI-12: how many private details were blurred automatically. */
+    autoBlurred?: number;
+};
+export type SubmitInput = {
+    type: ReportType;
+    message: string;
+    rating?: number;
+    email?: string;
+    shot?: Shot;
+    /** AI-10: the follow-up question and the visitor's answer. */
+    followUp?: {
+        question: string;
+        answer: string;
+    };
+    /** W-10: answers to the site's custom fields. */
+    fields?: FieldAnswer[];
+    /** W-19: the kind of accessibility barrier, when the visitor chose one. */
+    barrier?: Barrier;
+    /** P-04: the hidden honeypot field (people leave it empty). */
+    hp?: string;
+    /** P-04: milliseconds from opening the panel to sending. */
+    elapsedMs?: number;
+    /** Visitor consent: the visitor ticked "Include technical details". */
+    includeLogs?: boolean;
+    /** What the notice above Send said would go; nothing else is attached. */
+    listed?: {
+        logs: boolean;
+        replay: boolean;
+    };
+};
+/**
+ * Visitor consent: what goes with a report besides the note, for the
+ * notice above Send. `logs`: technical logs go as things stand; `askLogs`:
+ * they go only if the visitor ticks the box (shown then); `replay`: the
+ * last 30 seconds go.
+ */
+export type Attachments = {
+    logs: boolean;
+    askLogs: boolean;
+    replay: boolean;
+};
+/** AI-10: only short notes on problems and ideas get a follow-up question. */
+export declare const FOLLOW_UP_MAX_NOTE = 140;
+export type SubmitResult = {
+    status: 'sent';
+} | {
+    status: 'queued';
+} | {
+    status: 'error';
+    message: string;
+};
+export type UIHandlers = {
+    takeScreenshot(): Promise<Shot>;
+    markUp(shot: Shot): Promise<Shot | null>;
+    submit(input: SubmitInput): Promise<SubmitResult>;
+    user(): PinaxUser | undefined;
+    /** Called each time the panel opens (Segment). Must not throw. */
+    opened?(): void;
+    /**
+     * AI-10: one follow-up question for a short note, or null to send as is.
+     * Must resolve (to null) on errors and within a few seconds.
+     */
+    followUp?(input: {
+        type: ReportType;
+        message: string;
+    }): Promise<string | null>;
+    /** Known issues that match this page view, asked each time the panel opens. */
+    knownIssues?(): KnownIssue[];
+    /** Known issues: "Me too", with an email when given. False on any error. */
+    meToo?(id: string, email?: string): Promise<boolean>;
+    /**
+     * Visitor consent: what a report would carry now (see `Attachments`).
+     * Without it: technical logs, no box, no recording.
+     */
+    attachments?(): Attachments;
+    /** Who the report goes to, in the notice. Default: this page's host name. */
+    site?(): string;
+};
+/** A screen of the panel, or 'button' for the closed widget. */
+export type WidgetView = 'button' | 'choose' | 'problem' | 'idea' | 'general' | 'accessibility' | 'done';
+/**
+ * The floating button and the feedback panel (W-01, W-02, W-07 to W-11,
+ * W-15). Everything renders inside the shadow root.
+ */
+export declare class WidgetUI {
+    private root;
+    private config;
+    private handlers;
+    private wrap;
+    private launcher;
+    private panel;
+    private live;
+    private kinds;
+    private kind;
+    private shot;
+    private message;
+    private email;
+    /** The visitor typed in, changed or cleared an email box: never refill it. */
+    private emailEdited;
+    private rating;
+    /** W-19 */
+    private barrier;
+    /** W-10: answers by field id. */
+    private answers;
+    /** W-17: the client's colour on Send buttons (Agency). */
+    private sendColour;
+    private sending;
+    /** P-04: when the panel opened, and the honeypot field's value. */
+    private openedAt;
+    private hp;
+    private closeTimer;
+    private uid;
+    /** S-04 hidden path, set from outside as the visitor navigates. */
+    private pathHidden;
+    /** Where focus goes back to on close when there's no button to return to. */
+    private returnFocus;
+    /** Known issues matched when the panel last opened, and those the visitor moved past. */
+    private known;
+    private knownHidden;
+    private meToo;
+    /** Visitor consent: the "Include technical details" box, unticked to start. */
+    private includeLogs;
+    /** The notice above Send on show, and what it said would go. */
+    private privacy;
+    private noticeText;
+    private shown;
+    constructor(root: ShadowRoot, config: WidgetConfig, handlers: UIHandlers, 
+    /** Extra classes on the wrapper and extra CSS (the dashboard preview). */
+    extra?: {
+        className?: string;
+        css?: string;
+    });
+    isOpen(): boolean;
+    /** True while the floating button is on screen (S-04, S-05). */
+    hasButton(): boolean;
+    /**
+     * S-04: hide or show the floating button for the current page. An open
+     * panel stays open, and `open()` keeps working either way.
+     */
+    setPathHidden(hidden: boolean): void;
+    private updateButton;
+    /** `focus: false` opens without moving focus (the dashboard preview). */
+    open(focus?: boolean): void;
+    close(restoreFocus?: boolean): void;
+    /** The screen on show, for the dashboard preview. */
+    currentView(): WidgetView;
+    /**
+     * Dashboard preview: jump straight to a screen without moving focus. A
+     * type that's switched off shows the chooser instead.
+     */
+    showView(view: WidgetView): void;
+    /** S-06: the owner's wording, or ours when they left it empty. */
+    private word;
+    private kindTitle;
+    /** Hides the panel while the full-screen editor is up. */
+    private setSuspended;
+    destroy(): void;
+    private view;
+    private queued;
+    /** AI-10: the question asked about `message`, and the answer so far. */
+    private asked;
+    private answer;
+    private reset;
+    private holdOpen;
+    private focusFirst;
+    private announce;
+    private pick;
+    private capture;
+    private markUp;
+    private renderKeepingFocus;
+    private header;
+    private powered;
+    /** W-17: the client's logo at the top of the panel (Agency). */
+    private logo;
+    private render;
+    private renderChoose;
+    /** Known issues: the matches on show, without those the visitor moved past. */
+    private knownShown;
+    /** Asks which known issues match now; with any, the panel starts on the card. */
+    private offerKnown;
+    /**
+     * Known issues: "We know about this", each issue's public title and a
+     * Me too button; after it, thanks and (when the site allows it) "Email me
+     * when it's fixed". "Report something else" leaves the card.
+     */
+    private renderKnown;
+    /** Me too, or (with `emailEl`) the email to hear when it's fixed. */
+    private sendMeToo;
+    private renderShot;
+    private renderStars;
+    private renderForm;
+    /** The optional email, the honeypot, the error line and Send. */
+    private renderEmailAndSend;
+    /** Visitor consent: what a report would carry now. */
+    private attachments;
+    /**
+     * Above Send: the "Include technical details" box (only while the page
+     * waits for consent and the visitor hasn't given it), then what goes
+     * with the note, and the site's privacy policy.
+     */
+    private renderPrivacy;
+    /** "Sent to … with your note: …", listing only what will go. */
+    private updateNotice;
+    /**
+     * Consent changed, or the recorder started: the notice (and the box)
+     * above Send follow, in place, so typing and focus aren't disturbed.
+     */
+    refresh(): void;
+    /**
+     * W-19: a short form that works well with a screen reader and the
+     * keyboard alone: native radio buttons, real labels, no screenshot unless
+     * the visitor adds one, and a note saying who reads it.
+     */
+    private renderAccessibility;
+    /**
+     * P-04: a field people never see or reach (off-screen, out of the tab
+     * order and hidden from screen readers). Form-filling bots fill it in.
+     */
+    private honeypot;
+    private send;
+    /** The follow-up question for this note, or null (no question, error, timeout). */
+    private askFollowUp;
+    private submitNow;
+    /** AI-10: one question about the note, with "Send" and "Skip and send". */
+    private renderQuestion;
+    /** W-17: the client's colour on Send, else the colour of the kind. */
+    private colourSend;
+    /** W-10: the owner's fields for this kind of feedback. */
+    private fieldsFor;
+    private fieldAnswers;
+    /** W-10: dropdowns, short text and checkboxes, labelled and keyboard friendly. */
+    private renderFields;
+    private renderDone;
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@getpinax/widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.2",
+  "type": "module",
+  "description": "Pinax website feedback widget: a feedback button with screenshots, markup and page context",
+  "license": "MIT",
+  "author": "Pinax <hello@getpinax.com>",
+  "homepage": "https://getpinax.com",
+  "bugs": {
+    "email": "hello@getpinax.com"
+  },
+  "keywords": [
+    "feedback",
+    "bug-report",
+    "widget",
+    "screenshot",
+    "pinax"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/pinax.mjs",
+  "module": "./dist/pinax.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/pinax.mjs"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build && vite build --mode editor && vite build --mode recorder && vite build --mode axe && vite build --mode embed && tsc -p tsconfig.build.json && node scripts/check-size.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check ./src ./cdn",
+    "check:fix": "biome check --write ./src ./cdn",
+    "size": "node scripts/check-size.mjs",
+    "playground": "yarn build && node scripts/serve-playground.mjs",
+    "prepublishOnly": "VITE_PINAX_API=https://api.getpinax.com VITE_PINAX_CDN=https://cdn.getpinax.com yarn build && yarn test",
+    "cdn:deploy": "./cdn/deploy.sh",
+    "release": "bash scripts/release.sh"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.5",
+    "@types/node": "^22",
+    "jsdom": "^30.1.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  },
+  "dependencies": {
+    "@rrweb/record": "2.1.7",
+    "axe-core": "^4.10.0",
+    "modern-screenshot": "^4.7.0"
+  },
+  "resolutions": {
+    "rrweb": "2.1.7",
+    "rrweb-snapshot": "2.1.7",
+    "rrdom": "2.1.7",
+    "@rrweb/types": "2.1.7",
+    "@rrweb/utils": "2.1.7"
+  }
+}