@e-llm-studio/feedback-flow 0.0.0-stage → 0.1.31

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# Response feedback components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`useFeedbackFlow(requestId, featureId)` owns the rating and draft for one response. Render `FeedbackPrompt` and `FeedbackModal` with the same controller. The caller decides where to place the prompt and supplies the modal's `anchorRef` so the popup appears above it.
+
+For chat timelines, `FeedbackResponseControls` owns that controller per response. Give it the response's `requestId`, `featureId`, message index, chat shell and sticky host refs, and viewport state. It renders one prompt at the heading for a newly completed response, beside the response's actions at its end, or in the sticky host while that response is active in the viewport. Each response keeps a separate draft.
+
+```tsx
+const flow = useFeedbackFlow(requestId, featureId);
+const promptRef = useRef<HTMLDivElement>(null);
+const copy = createFeedbackCopy({
+  prompt: 'Rate this answer',
+  timeOptions: [5, 15, 30].map((value) => ({ value, label: `${value} minutes` })),
+  severityLabels: { critical: 'Blocking' },
+});
+const theme = { accent: '#6d28d9', text: '#1e293b', muted: '#64748b' };
+
+return <>
+  <FeedbackPrompt flow={flow} promptRef={promptRef} copy={copy} theme={theme} />
+  <FeedbackModal
+    flow={flow}
+    anchorRef={promptRef}
+    copy={copy}
+    theme={theme}
+    slots={{ gap: <YourOptionalGapContent /> }}
+    onSubmit={(feedback) => submitFeedback(feedback)}
+  />
+</>;
+```
+
+`createFeedbackCopy` accepts partial overrides for every visible label, question, hint, placeholder, and option. `FeedbackTheme` controls the prompt, popup, tooltip, overlay, and severity colors. `slots` and `extraContent` allow callers to add their own React content. The `onSubmit` payload includes the request ID, feature ID, numeric rating, time saved, useful text, gap descriptions, impact levels, and screenshot `File` objects.
+
+Useful and gap answers shorter than `usefulMinimumWords` show a configurable helper directly below their question and keep the existing answer in the same textarea. Continue is hidden until the minimum is met. Decimal ratings advance on selection without an Enter hint. Each completed step is saved by POST or PATCH with `metadata.feedbackProgress`; an interrupted response reopens at its next unanswered step, while only the final save marks feedback complete. The remote template's local tarball must be updated separately to receive these source changes.
+
+`FeedbackExperience` and `FeedbackResponseControls` use `mockFeedbackApi` by default. The mock stores records in browser `localStorage` (with an in-memory fallback), and fetches an existing record on mount so Review can reopen previously submitted answers. `upsertFeedback` handles both first submission and later edits; `getFeedback` looks up a record by `query_id`, `feature_id`, and `user_email`. Supply a custom `FeedbackApi` through the `api` prop when a backend is available. The host's `onSubmit` callback still runs after a successful save.
+
+The API record mirrors the proposed tables: `feedback_form`, `positive_feedback`, `gaps`, and `feedback_attachment`. Chat `query_id` comes from tracking metadata; feature feedback only needs `featureId`. `user_email`/`trace_id` come from tracking. IDs and timestamps remain stable on updates. Embeddings are backend-generated and omitted. Screenshot references use `mock://` URLs until an upload endpoint exists; the mock does not upload file bytes.
+
+`createHttpFeedbackApi({ baseUrl, readBaseUrl, getAuthToken, uploadAttachment })` reads chat feedback with GET `/feedback?user_email=...&session_id=...` and non-chat feedback with GET `/feedback?user_email=...&feature_id=...`. When a session ID is supplied, the GET never falls back to `feature_id`, even if the response query ID is not available yet. It selects the relevant chat record from the session's results by its `query_id`. POST creates and PATCH `/feedback/{feedback_id}` updates records. A chat submission requires `metadata.queryId` and sends `query_id`; non-chat feedback sends `feature_id`, never both. If the non-chat feature ID is not a UUID, the adapter derives a stable UUID-shaped ID from the host IDs. `getAuthToken` supplies a fresh Bearer token for every GET, POST, and PATCH request. `readBaseUrl` is optional when reads use a different deployment. Browser-local state is only a fallback when GET fails. The request body follows the live API's `positive_feedback` and `negative_feedback` arrays. Hosts can provide an upload function; it must upload each `File` and return its `gs://` URL before the feedback request is sent. Original host IDs remain in metadata for matching older records.
+
+Hosts may include `metadata.queryId`, `metadata.sessionId`, and `metadata.requestId` to send top-level `query_id`, `session_id`, and `request_id` with feedback. Chat reads filter by `session_id`, then match each response by `query_id`; `query_id` is never a GET parameter. All three are optional for non-chat integrations. `FeedbackExperience.requestId` is optional for features; its internal UI identity falls back to `featureId`, but no `request_id` or `query_id` is sent in the feature API payload.
+
+For screenshots, use `createFeedbackScreenshotUploader({ baseUrl: VITE_BASE_API_URL, getAuthToken })` as `uploadAttachment` and `createFeedbackScreenshotUrlResolver` with the same options as `getAttachmentPreviewUrl`. The library POSTs the file as multipart form data to `/backend/gcs/direct-gcs-upload` (or `/gcs/direct-gcs-upload` when the base URL already ends in `/backend`) and sends the returned `gs_url` in the feedback attachment payload. To preview a saved screenshot, it POSTs `{ gsutil_url: gsUrl }` to CW's `/gcs/get-signed-url/` and uses the returned short-lived `signed_url`, rather than the upload response's unsigned `public_url`. Signed URLs are cached in memory by API base URL, auth token, and GCS path until just before expiry; concurrent requests share one call, and a failed image can force-refresh its URL. Clicking the thumbnail opens a larger preview; the remove icon takes that screenshot out of the draft and subsequent feedback payload without deleting the GCS object. The form shows an error and stays open if upload or feedback submission fails. No project ID is needed for this endpoint.
+
+For mode tracking, pass `tracking` to `FeedbackExperience`, or call `createFeedbackMetadata(tracking)` when using `useFeedbackFlow` directly. Standard fields are `mode`, `modeId`, `owner`, `featureContext`, `userEmail`, and `traceId`. Put any integration-specific fields under `custom`; they are included alongside the standard fields in `submission.metadata`. For example:
+
+```tsx
+<FeedbackExperience
+  featureId={featureId}
+  featureAvailabilityModeId={modeId}
+  featureAvailabilityApi={createHttpFeatureAvailabilityApi({
+    baseUrl: 'https://devllmstudio.creativeworkspace.ai',
+    getAuthToken: () => authStore.getState().token,
+  })}
+  tracking={{
+    mode: 'Agent Genie',
+    modeId,
+    owner: user.email,
+    featureContext: 'BlockedIncidents',
+  }}
+  onSubmit={(feedback) => saveFeedback(feedback)}
+/>
+```
+
+The availability API is consulted only when `requestId` is omitted. It GETs `/segment_click_analytics/v1/api/mode-features/{modeId}` with the current Bearer token, shares one list request across cards, and matches `feature_id`. A feature card is hidden until its matching response arrives. Each non-null `start_date`, `end_date`, and `ui_new_ttl` is checked; a null field adds no restriction. Missing features or failed responses hide the card. `createMockFeatureAvailabilityApi` remains available for tests. The existing `metadata` prop still works. When both are provided, explicit standard fields in `tracking` take precedence. The components use default copy when it is omitted or incomplete. `FeedbackErrorBoundary` can wrap each surface so a rendering error hides only the feedback UI. The modal also tolerates browsers without `ResizeObserver` and shows a retry message only if the final save fails.

package/dist/FeedbackErrorBoundary.d.ts

@@ -0,0 +1,17 @@
+import { Component, type ReactNode } from 'react';
+interface Props {
+    children: ReactNode;
+    resetKey: string;
+}
+interface State {
+    failed: boolean;
+}
+/** A feedback rendering failure must not replace the surrounding chat. */
+export declare class FeedbackErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error): void;
+    componentDidUpdate(previousProps: Props): void;
+    render(): ReactNode;
+}
+export {};

package/dist/FeedbackErrorBoundary.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackErrorBoundary = void 0;
+const react_1 = require("react");
+/** A feedback rendering failure must not replace the surrounding chat. */
+class FeedbackErrorBoundary extends react_1.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        console.error('Feedback UI failed to render', error);
+    }
+    componentDidUpdate(previousProps) {
+        if (previousProps.resetKey !== this.props.resetKey && this.state.failed) {
+            this.setState({ failed: false });
+        }
+    }
+    render() {
+        return this.state.failed ? null : this.props.children;
+    }
+}
+exports.FeedbackErrorBoundary = FeedbackErrorBoundary;

package/dist/FeedbackExperience.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type FeedbackCopy, type FeedbackExperienceClassNames, type FeedbackExperienceStyles, type FeedbackMetadata, type FeedbackSubmission, type FeedbackTheme, type FeedbackTrackingContext } from "./types";
+import type { FeedbackApi } from "./feedbackApi";
+import { type FeatureAvailabilityApi } from "./featureAvailability";
+export interface FeedbackExperienceProps {
+    /** Optional for feature-level feedback; chat responses should provide their request ID. */
+    requestId?: string;
+    featureId: string;
+    /** Consulted only for feature-level feedback, never for chat responses. */
+    featureAvailabilityApi?: FeatureAvailabilityApi;
+    /** Backend mode UUID used to list its features. */
+    featureAvailabilityModeId?: string;
+    metadata?: FeedbackMetadata;
+    tracking?: FeedbackTrackingContext;
+    copy?: Partial<FeedbackCopy>;
+    theme?: FeedbackTheme;
+    onSubmit?: (submission: FeedbackSubmission) => void | Promise<void>;
+    api?: FeedbackApi;
+    className?: string;
+    style?: CSSProperties;
+    styles?: FeedbackExperienceStyles;
+    classNames?: FeedbackExperienceClassNames;
+    align?: "start" | "center" | "end";
+    slots?: Partial<Record<"rating" | "time" | "gap" | "success", ReactNode>>;
+}
+/** Standalone experience for hosts that do not need chat-specific anchoring. */
+export declare function FeedbackExperience(props: FeedbackExperienceProps): JSX.Element | null;

package/dist/FeedbackExperience.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackExperience = FeedbackExperience;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_dom_1 = require("react-dom");
+const FeedbackErrorBoundary_1 = require("./FeedbackErrorBoundary");
+const FeedbackModal_1 = require("./FeedbackModal");
+const FeedbackPrompt_1 = require("./FeedbackPrompt");
+const types_1 = require("./types");
+const tracking_1 = require("./tracking");
+const useFeedbackFlow_1 = require("./useFeedbackFlow");
+const useFeedbackPersistence_1 = require("./useFeedbackPersistence");
+const featureAvailability_1 = require("./featureAvailability");
+/** Standalone experience for hosts that do not need chat-specific anchoring. */
+function FeedbackExperience(props) {
+    const available = (0, featureAvailability_1.useFeatureAvailability)(props.featureAvailabilityModeId, props.featureId, props.featureAvailabilityApi, !props.requestId);
+    if (!available)
+        return null;
+    return (0, jsx_runtime_1.jsx)(FeedbackExperienceContent, { ...props, requestId: props.requestId || props.featureId });
+}
+function FeedbackExperienceContent({ requestId, featureId, metadata, tracking, copy, theme, onSubmit, api, className, style, styles, classNames, align = "start", slots, }) {
+    const feedbackMetadata = (0, tracking_1.createFeedbackMetadata)(tracking, metadata);
+    const flow = (0, useFeedbackFlow_1.useFeedbackFlow)(requestId, featureId, feedbackMetadata);
+    const { saveFeedback, saveProgress, saveOnDismiss, isLoading, isSaving, saveError } = (0, useFeedbackPersistence_1.useFeedbackPersistence)(flow, feedbackMetadata, onSubmit, api);
+    const anchorRef = (0, react_1.useRef)(null);
+    const [promptPosition, setPromptPosition] = (0, react_1.useState)(null);
+    const prompt = ((0, jsx_runtime_1.jsx)(FeedbackPrompt_1.FeedbackPrompt, { flow: flow, loading: isLoading, disabled: isSaving, promptRef: anchorRef, copy: copy ?? types_1.defaultFeedbackCopy, theme: theme, styles: styles?.prompt, classNames: classNames?.prompt, onRatingSelected: (rating) => {
+            const nextStep = rating === 3 || rating === 4 ? "rating" : rating <= 2 ? "gap" : "time";
+            void saveProgress({ requestId, featureId, rating, gaps: [], metadata: feedbackMetadata }, nextStep)
+                .catch((error) => console.error("Could not save rating", error));
+        }, onBeforeOpen: () => {
+            const rect = anchorRef.current?.getBoundingClientRect();
+            if (rect)
+                setPromptPosition({ left: rect.left, top: rect.top });
+        } }));
+    const floating = flow.step !== "closed" && promptPosition && typeof document !== "undefined";
+    return ((0, jsx_runtime_1.jsx)(FeedbackErrorBoundary_1.FeedbackErrorBoundary, { resetKey: requestId, children: (0, jsx_runtime_1.jsxs)("div", { className: [className, classNames?.container].filter(Boolean).join(" "), style: {
+                display: "flex",
+                justifyContent: align === "end" ? "flex-end" : align === "center" ? "center" : "flex-start",
+                ...style,
+                ...styles?.container,
+            }, children: [floating
+                    ? (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsx)("div", { className: classNames?.floatingWrapper, style: {
+                            position: "fixed",
+                            left: promptPosition.left,
+                            top: promptPosition.top,
+                            zIndex: 10002,
+                            width: "max-content",
+                            maxWidth: "calc(100vw - 24px)",
+                            ...styles?.floatingWrapper,
+                        }, children: prompt }), document.body)
+                    : prompt, (0, jsx_runtime_1.jsx)(FeedbackModal_1.FeedbackModal, { flow: flow, anchorRef: anchorRef, copy: copy, theme: theme, onSubmit: saveFeedback, onProgress: saveProgress, onDismiss: saveOnDismiss, saveError: saveError, resolveScreenshotUrl: api?.getAttachmentPreviewUrl, slots: slots, styles: styles?.modal, classNames: classNames?.modal })] }) }));
+}

package/dist/FeedbackModal.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode, type RefObject } from 'react';
+import { type FeedbackCopy, type FeedbackModalClassNames, type FeedbackModalStyles, type FeedbackProgressStep, type FeedbackSubmission, type FeedbackTheme } from './types';
+import type { FeedbackFlowController } from './useFeedbackFlow';
+export interface FeedbackModalProps {
+    flow: FeedbackFlowController;
+    copy?: Partial<FeedbackCopy>;
+    theme?: FeedbackTheme;
+    onSubmit?: (feedback: FeedbackSubmission) => void | Promise<void>;
+    onProgress?: (feedback: FeedbackSubmission, nextStep: FeedbackProgressStep) => Promise<void>;
+    onDismiss?: (feedback: FeedbackSubmission, nextStep: FeedbackProgressStep, completed: boolean) => Promise<void>;
+    saving?: boolean;
+    saveError?: boolean;
+    resolveScreenshotUrl?: (gcsUrl: string, forceRefresh?: boolean) => Promise<string>;
+    anchorRef: RefObject<HTMLDivElement>;
+    overlayHostRef?: RefObject<HTMLElement>;
+    anchorKey?: boolean;
+    slots?: Partial<Record<'rating' | 'time' | 'gap' | 'success', ReactNode>>;
+    className?: string;
+    style?: CSSProperties;
+    styles?: FeedbackModalStyles;
+    classNames?: FeedbackModalClassNames;
+    backdropClassName?: string;
+    backdropStyle?: CSSProperties;
+    dialogClassName?: string;
+    dialogStyle?: CSSProperties;
+}
+export declare function FeedbackModal(props: FeedbackModalProps): JSX.Element | null;