@lightworkai.official/debug-capture-react 0.6.0

package/README.md

@@ -0,0 +1,85 @@
+# @lightworkai.official/debug-capture-react
+
+React bindings for [`@lightworkai.official/debug-capture`](../debug-capture/README.md).
+
+```tsx
+// app entry
+import { configureDebugCapture } from "@lightworkai.official/debug-capture-react";
+
+configureDebugCapture({
+  host: "https://support.example.com",
+  realmKey: "pk_live_…",
+  app: { version: "1.4.2", environment: "production" },
+  user: () => ({ id: me.id, email: me.email, fullName: me.name, unit: me.unit }),
+});
+```
+
+```tsx
+// root layout — once, above the routes
+<DebugCaptureInit />
+
+// wherever the button belongs, styled by you
+<ReportProblemButton className="rounded-lg p-2 hover:bg-gray-100" />
+```
+
+## Components
+
+| | |
+| --- | --- |
+| `<DebugCaptureInit />` | Arms the buffers, mounts the reporter. Renders nothing. |
+| `<ReportProblemButton />` | Opens the reporter. Unstyled; `className` and children are yours. |
+| `<DebugErrorBoundary />` | Catches a render crash and offers to report it. |
+| `<MyTicketsPanel />` | The reporter's own tickets — list, detail, conversation, reopen. |
+
+`DebugErrorBoundary` is the one thing React needs that Vue and Angular do not: a
+render error never reaches `window.onerror`, so the core's crash watcher cannot
+see it. Those are the crashes users describe as "the screen went white".
+
+## Notes
+
+**Mount `DebugCaptureInit` above the routes.** The buffers have to be recording
+*before* a user hits a problem. A report opened from a page that only just
+started listening has no trail of how the user got there, which is the half that
+makes it reproducible.
+
+**Do not wrap the button in anything that awaits.** `launch` runs straight out
+of the click because screen capture is gated on a user gesture — one `await`
+between the click and `getDisplayMedia` loses it, and the browser refuses with
+an error that explains nothing.
+
+**Failed queries are opt-in**, so this package never depends on a data library:
+
+```tsx
+<DebugCaptureInit
+  errorQueries={() =>
+    queryClient.getQueryCache().findAll()
+      .filter((q) => q.state.status === "error")
+      .map((q) => ({ key: JSON.stringify(q.queryKey), error: String(q.state.error) }))}
+/>
+```
+
+**`MyTicketsPanel` needs `identity` in the config** — a token your *server*
+signs. `realmKey` is public, so it can authorise filing a report but never
+reading one back; see [the core README](../debug-capture/README.md#it-needs-to-know-who-is-asking).
+Put the panel on a route of your own:
+
+```tsx
+export default function SupportPage() {
+  return <MyTicketsPanel />;   // or openMyTickets() for a modal
+}
+```
+
+It is a real React component now — props, callbacks, and children where they
+make sense — not a web component mounted through a ref. The logic it arranges
+lives in the core and is shared with the Vue and Angular packages.
+
+Import the stylesheet once, from anywhere:
+
+```ts
+import "@lightworkai.official/debug-capture/style.css";
+```
+
+**TipTap is a peer dependency** (`@tiptap/react` + starter-kit, image,
+placeholder) — the reply box is the same editor the team uses. Pass `refreshKey`
+to make the panel re-read its list, and `onError` to route failures into your own
+notification system.

package/dist/DebugCaptureInit.d.ts

@@ -0,0 +1,25 @@
+import { type DebugCaptureConfig, type ErroredQuery, type InstallOptions } from "@lightworkai.official/debug-capture";
+export interface DebugCaptureInitProps extends InstallOptions {
+    /**
+     * The config. Pass it here rather than calling `configureDebugCapture`
+     * yourself from a parent's effect — React runs CHILD effects before parent
+     * ones, so a parent that configures in `useEffect` runs *after* this
+     * component has already tried to install, and capture never arms.
+     *
+     * Calling `configureDebugCapture` at module scope also works, and is what the
+     * README shows. This exists so the wrong order is not reachable.
+     */
+    config?: DebugCaptureConfig;
+    /**
+     * Failed queries from the app's data layer, if it has one. A callback so this
+     * package never depends on react-query or any other client — with TanStack
+     * Query that is:
+     *
+     *   errorQueries={() =>
+     *     queryClient.getQueryCache().findAll()
+     *       .filter((q) => q.state.status === 'error')
+     *       .map((q) => ({ key: JSON.stringify(q.queryKey), error: String(q.state.error) }))}
+     */
+    errorQueries?: () => ErroredQuery[];
+}
+export declare function DebugCaptureInit({ config, errorQueries, ...options }: DebugCaptureInitProps): null;

package/dist/DebugErrorBoundary.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Catches a render crash and offers to report it.
+ *
+ * A React render error does NOT reach window.onerror, so the crash watcher in
+ * the core never sees it — this is the only way those get captured at all, and
+ * they are the ones users describe as "the screen went white".
+ *
+ * Class component because that is the only thing React gives us:
+ * componentDidCatch has no hook equivalent.
+ */
+import { Component, type ErrorInfo, type ReactNode } from "react";
+interface Props {
+    children: ReactNode;
+    /** What to show instead of the crashed subtree. */
+    fallback?: (error: Error, report: () => void) => ReactNode;
+}
+interface State {
+    error: Error | null;
+}
+export declare class DebugErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/dist/ReportProblemButton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The bug icon that opens the reporter.
+ *
+ * `launch` runs straight out of the click with nothing awaited in front of it.
+ * That is not style: screen capture is gated on a user gesture, and a single
+ * await between the click and `getDisplayMedia` loses it — the browser then
+ * refuses with an error that says nothing about why.
+ *
+ * It arrives presentable and `className` replaces that entirely. Shipping it
+ * unstyled meant every host wrote the same forty characters of CSS to make a
+ * bug icon look like a header button — work the library should have done. But
+ * the default must be *replaceable*, not merged: a widget with opinions about
+ * its border radius that you cannot override is a widget somebody has to fight.
+ */
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+export interface ReportProblemButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Replace the default bug glyph — pass the host's own icon component. */
+    children?: ReactNode;
+    label?: string;
+}
+export declare function ReportProblemButton({ children, label, className, style, onClick, ...rest }: ReportProblemButtonProps): import("react").JSX.Element;

package/dist/components/ImageAnnotatorDialog.d.ts

@@ -0,0 +1,11 @@
+export interface ImageAnnotatorDialogProps {
+    /** The picked image, as a same-origin data URI. */
+    src: string;
+    /** Shown in the description, as the app's dialog does. */
+    filename?: string;
+    locale: "th" | "en" | undefined;
+    /** The annotated image, at full resolution. */
+    onConfirm: (dataUri: string) => void;
+    onCancel: () => void;
+}
+export declare function ImageAnnotatorDialog({ src, filename, locale, onConfirm, onCancel }: ImageAnnotatorDialogProps): import("react").JSX.Element;

package/dist/components/MyTicketsPanel.d.ts

@@ -0,0 +1,11 @@
+import { type MyTicketDetail } from "@lightworkai.official/debug-capture";
+export interface MyTicketsPanelProps {
+    /** Change it to re-read the list — after filing a report, say. */
+    refreshKey?: string | number;
+    /** Hide the panel's own heading when the host page already has one. */
+    hideTitle?: boolean;
+    onReplied?: (ticket: MyTicketDetail) => void;
+    onReopened?: (ticket: MyTicketDetail) => void;
+    onError?: (message: string) => void;
+}
+export declare function MyTicketsPanel({ refreshKey, hideTitle, onReplied, onReopened, onError }: MyTicketsPanelProps): import("react").JSX.Element;

package/dist/components/ReopenPanel.d.ts

@@ -0,0 +1,7 @@
+import type { TicketStrings } from "@lightworkai.official/debug-capture";
+export declare function ReopenPanel({ t, locale, busy, onReopen, }: {
+    t: TicketStrings;
+    locale: "th" | "en";
+    busy?: boolean;
+    onReopen: (note: string) => void;
+}): import("react").JSX.Element;

package/dist/components/RichReplyEditor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The toolbar's words.
+ *
+ * An open map because the toolbar is configurable — a host asking for `strike`
+ * or `blockquote` needs a label for it, and enumerating every possible control
+ * here would mean editing this type every time one is added.
+ */
+export type EditorLabels = Record<string, string>;
+export interface RichReplyEditorHandle {
+    /** Sanitised HTML, or "" when there is nothing worth sending. */
+    value: () => string;
+    clear: () => void;
+    focus: () => void;
+}
+export interface RichReplyEditorProps {
+    placeholder: string;
+    /** Support host origin — the sanitiser resolves inline image URLs against it. */
+    host: string;
+    disabled?: boolean;
+    labels: EditorLabels;
+    /** Store an image and return the URL to reference it by. */
+    uploadImage: (file: File) => Promise<string>;
+    onError: (message: string) => void;
+    /** UI language, for the annotator's own labels. */
+    locale?: "th" | "en";
+    /** Content to start from — editing an existing message rather than writing one. */
+    initial?: string;
+}
+export declare const RichReplyEditor: import("react").ForwardRefExoticComponent<RichReplyEditorProps & import("react").RefAttributes<RichReplyEditorHandle>>;

package/dist/components/StatusHero.d.ts

@@ -0,0 +1,8 @@
+import type { MyTicketDetail, StatusMaps, TicketStrings } from "@lightworkai.official/debug-capture";
+export declare function StatusHero({ ticket, maps, locale, host, }: {
+    ticket: MyTicketDetail;
+    maps: StatusMaps;
+    t: TicketStrings;
+    locale: "th" | "en";
+    host: string;
+}): import("react").JSX.Element;

package/dist/components/StatusPill.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A status as the realm coloured it.
+ *
+ * The tone arrives as DATA — a realm adds lanes whenever it likes — so it is an
+ * inline style rather than a class. No stylesheet could know the names ahead of
+ * time.
+ */
+export declare function StatusPill({ label, tone }: {
+    label: string;
+    tone: {
+        fg: string;
+        bg: string;
+    };
+}): import("react").JSX.Element;

package/dist/components/TicketBody.d.ts

@@ -0,0 +1,5 @@
+export declare function TicketBody({ html, host, className }: {
+    html: string;
+    host: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/TicketConversation.d.ts

@@ -0,0 +1,13 @@
+import { type MyTicketDetail, type TicketStrings } from "@lightworkai.official/debug-capture";
+export declare function TicketConversation({ ticket, t, host, timezone, locale, sending, uploadImage, onSend, onEdited, onError, }: {
+    ticket: MyTicketDetail;
+    t: TicketStrings;
+    host: string;
+    timezone: string;
+    locale: "th" | "en" | undefined;
+    sending?: boolean;
+    uploadImage: (file: File) => Promise<string>;
+    onSend: (body: string) => void;
+    onEdited: () => void;
+    onError: (message: string) => void;
+}): import("react").JSX.Element;

package/dist/components/TicketDetail.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One report: what was filed, where it stands, what happened, and the thread.
+ * The order is the original's.
+ */
+import { type MyTicketDetail, type RealmConfig, type StatusEvent, type StatusMaps, type TicketStrings } from "@lightworkai.official/debug-capture";
+export declare function TicketDetail(props: {
+    ticket: MyTicketDetail;
+    history: StatusEvent[];
+    config: RealmConfig;
+    maps: StatusMaps;
+    t: TicketStrings;
+    host: string;
+    locale: "th" | "en" | undefined;
+    sending?: boolean;
+    reopening?: boolean;
+    uploadImage: (file: File) => Promise<string>;
+    attachmentUrl: (id: string) => Promise<string>;
+    onBack: () => void;
+    onSend: (body: string) => void;
+    onEdited: () => void;
+    onReopen: (note: string) => void;
+    onError: (message: string) => void;
+}): import("react").JSX.Element;

package/dist/components/TicketScreenshots.d.ts

@@ -0,0 +1,6 @@
+import type { TicketAttachment } from "@lightworkai.official/debug-capture";
+export declare function TicketScreenshots({ images, title, attachmentUrl, }: {
+    images: TicketAttachment[];
+    title: string;
+    attachmentUrl: (id: string) => Promise<string>;
+}): import("react").JSX.Element;

package/dist/components/TicketTable.d.ts

@@ -0,0 +1,18 @@
+import { type MyTicketListItem, type Sort, type SortKey, type StatusMaps, type TicketStrings } from "@lightworkai.official/debug-capture";
+export interface TicketTableProps {
+    items: MyTicketListItem[];
+    maps: StatusMaps;
+    t: TicketStrings;
+    slug: string | undefined;
+    timezone: string;
+    locale: "th" | "en" | undefined;
+    keyword: string;
+    statusFilter: string;
+    sort: Sort;
+    page: number;
+    onOpen: (id: string) => void;
+    onSort: (key: SortKey) => void;
+    onPage: (page: number) => void;
+    onCount?: (count: number) => void;
+}
+export declare function TicketTable(props: TicketTableProps): import("react").JSX.Element;

package/dist/components/TicketTimeline.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The lifecycle, chronologically — including a reopen, which is the event a
+ * fixed happy-path progress bar hides and the one a reporter most wants to see
+ * recorded.
+ */
+import { type StatusEvent, type StatusMaps } from "@lightworkai.official/debug-capture";
+export declare function TicketTimeline({ history, status, createdAt, maps, timezone, locale, }: {
+    history: StatusEvent[];
+    status: string;
+    createdAt: string;
+    maps: StatusMaps;
+    timezone: string;
+    locale: "th" | "en";
+}): import("react").JSX.Element;

package/dist/components/ToolbarButton.d.ts

@@ -0,0 +1,18 @@
+/**
+ * One editor toolbar button.
+ *
+ * It fires on `mousedown` with the default prevented, not on `click`, and that
+ * is the whole reason it is a component rather than a `<button>` repeated seven
+ * times: a toolbar button taking focus collapses the editor's selection, so by
+ * the time `click` fires the command has nothing to apply to. Getting that
+ * wrong is invisible until someone selects a word and presses B.
+ */
+import type { ReactNode } from "react";
+export interface ToolbarButtonProps {
+    label: string;
+    active?: boolean;
+    disabled?: boolean;
+    onActivate: () => void;
+    children: ReactNode;
+}
+export declare function ToolbarButton({ label, active, disabled, onActivate, children }: ToolbarButtonProps): import("react").JSX.Element;

package/dist/components/icons.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The panel's icons, drawn rather than imported.
+ *
+ * The original uses lucide, and a package that pulled an icon set in so a reply
+ * box could show a B would cost every consumer that dependency. These are the
+ * same lucide paths at the same 24-unit scale.
+ */
+import type { SVGProps } from "react";
+export declare const BoldIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ItalicIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const UnderlineIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const BulletListIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const OrderedListIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const LinkIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ImageIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const SendIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const SearchIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowLeftIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const CheckIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const MessageIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const RotateIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const AlertIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const InboxIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ClockIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const CheckCircleIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const BanIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const WrenchIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const SquareIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowUpRightIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const HighlighterIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const TypeIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const TrashIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const PencilIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const CheckSmallIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const XSmallIcon: (props: SVGProps<SVGSVGElement>) => import("react").JSX.Element;

package/dist/crash.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Announce a render crash on the same channel as an uncaught error, so a host
+ * that already listens for crashes gets these too without a second wiring.
+ */
+export declare function emitCrashFromBoundary(error: Error, componentStack?: string): void;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * React bindings for @lightworkai.official/debug-capture.
+ *
+ * Thin on purpose: the dialog, the annotator and the capture all live in the
+ * core as one custom element, so these three components are a mount, a click
+ * and an error boundary. Everything a Vue or Angular host gets, a React host
+ * gets from the same code.
+ */
+export { DebugCaptureInit } from "./DebugCaptureInit";
+export type { DebugCaptureInitProps } from "./DebugCaptureInit";
+export { ReportProblemButton } from "./ReportProblemButton";
+export type { ReportProblemButtonProps } from "./ReportProblemButton";
+export { DebugErrorBoundary } from "./DebugErrorBoundary";
+export { MyTicketsPanel } from "./components/MyTicketsPanel";
+export type { MyTicketsPanelProps } from "./components/MyTicketsPanel";
+export { TicketTable } from "./components/TicketTable";
+export { TicketDetail } from "./components/TicketDetail";
+export { TicketConversation } from "./components/TicketConversation";
+export { RichReplyEditor } from "./components/RichReplyEditor";
+export { TicketBody } from "./components/TicketBody";
+export { ImageAnnotatorDialog } from "./components/ImageAnnotatorDialog";
+export { configureDebugCapture, launch, onCrash } from "@lightworkai.official/debug-capture";
+export type { DebugCaptureConfig, DebugReason, ErroredQuery, MyTicketListItem, MyTicketDetail } from "@lightworkai.official/debug-capture";