@e-llm-studio/feedback-flow

Reusable React components for star ratings and progressive feedback. The package includes the prompt, follow-up screens, persistence helpers, and optional feature-details lookup. Its stylesheet is imported by the package entry point.

Install

Install @e-llm-studio/feedback-flow alongside its peer dependencies: react, react-dom, and lucide-react.

Quick start

FeedbackExperience provides the complete flow. Pass a FeedbackApi to persist feedback to your backend; if api is omitted, the package uses browser-local mock storage instead. The HTTP adapter uses the API only, not localStorage.

import {
  FeedbackExperience,
  createFeedbackTheme,
  createHttpFeedbackApi,
  createHttpFeatureAvailabilityApi,
} from '@e-llm-studio/feedback-flow';

const getAuthToken = () => authStore.getState().token ?? undefined;
const feedbackApi = createHttpFeedbackApi({
  baseUrl: apiBaseUrl,
  getAuthToken,
});
const featureAvailabilityApi = createHttpFeatureAvailabilityApi({
  baseUrl: apiBaseUrl,
  getAuthToken,
});

export function FeatureFeedback() {
  return (
    <FeedbackExperience
      api={feedbackApi}
      featureId={featureId}
      featureAvailabilityApi={featureAvailabilityApi}
      featureAvailabilityModeId={modeId}
      userEmail={userEmail}
      environment="dev"
      tracking={{ mode: 'My mode', modeId, featureContext: 'my-feature' }}
      copy={{
        prompt: 'Was this feature Helpful?',
        usefulTitle: 'What worked well?',
        gapTitle: 'What should we improve?',
      }}
      theme={createFeedbackTheme({ accent: '#6025e5' })}
    />
  );
}

The example assumes authStore, apiBaseUrl, featureId, modeId, and userEmail come from your host app. Keep adapters outside the component when their configuration is stable. The feature-details adapter and mode ID are optional: the card remains visible if the feature is missing or the lookup fails. While ui_new_ttl is in the future, the card shows a New badge; expiry removes only the badge. start_date and end_date do not currently control visibility.

Each feature-card mount starts a fresh feedback form. The clock button in its modal loads earlier forms from the supplied API; today's forms can be reopened for editing, while older forms are shown read-only. FeedbackApi.listFeedback supplies that history (createHttpFeedbackApi implements it). The same-day edit restriction is enforced by this UI; the backend should enforce it too if updates can be called directly.

Feature cards use ratingCardLayout="vertical" by default, with the badge and prompt above the stars. Set ratingCardLayout="horizontal" to put the badge, prompt, and stars on one line. Give the horizontal card enough room in its host container.

For a chat response, pass a stable requestId and include its backend queryId and sessionId in metadata. A response with requestId does not call the feature-availability API.

Customize

• copy overrides built-in questions, labels, hints, placeholders, and options. usefulMinimumWords defaults to five.
• theme, styles, and classNames control colors and presentation. slots adds content to the rating, time, gap, or success screen.
• tracking adds host context to saved metadata; use custom for additional fields. onSubmit runs after a successful save.
• createFeedbackScreenshotUploader and createFeedbackScreenshotUrlResolver can be supplied to createHttpFeedbackApi when the host supports attachments.
• captureScreenshot lets a host capture the current tab. It should return an image File, Blob, or PNG/JPEG/WebP data URL; return null if cancelled. Without it, the library uses the browser's screen-sharing picker.

For an extension, capture in its background/service worker and pass the result through extension messaging. The library hides its modal before calling the adapter:

<FeedbackExperience
  // ...other props
  captureScreenshot={async () => {
    const result = await chrome.runtime.sendMessage({ type: 'ECG_CAPTURE_FEEDBACK_TAB' });
    if (result.error) throw new Error(result.error);
    return result.dataUrl ?? null;
  }}
/>

The extension must implement that message handler using chrome.tabs.captureVisibleTab and have the required tab/host permission. If the React UI runs in a regular web page rather than an extension context, bridge the request through a content script instead of calling chrome.runtime from the page.

These options customize the existing flow; adding new fields or changing its branching requires custom host UI or a library change.

Lower-level composition

For response/query feedback, pass queryId directly instead of featureId:

<FeedbackExperience
  queryId={queryId}
  requestId={requestId}
  sessionId={sessionId}
  userEmail={userEmail}
  environment="dev"
  api={feedbackApi}
/>

requestId and sessionId are optional correlation identifiers. Feature feedback uses featureId; query feedback uses queryId. Use metadata for extra application fields and tracking for mode/feature context. Lower-level callers can use useFeedbackFlow({ queryId, requestId, sessionId, userEmail, environment }) or useFeedbackFlow({ featureId, userEmail, environment }). The older positional hook signature is retained for existing consumers.

Pass the deployment environment through metadata={{ environment: "stage" }} or tracking={{ environment: "stage" }}. Saves default to dev when no environment is supplied. The cw-core integration reads config.VITE_CURRENT_ENV; the remote feature wrapper also accepts an environment prop.

Ratings below 4 do not create a feedback form or upload attachments until the user completes the gaps step. Selecting a low rating or dismissing that step alone does not save it.

For independent prompt/modal placement, use useFeedbackFlow, FeedbackPrompt, and FeedbackModal with the same flow controller and an anchorRef. Use useFeedbackPersistence with a FeedbackApi to load and save feedback, and wire its save handlers to the modal. FeedbackExperience handles this wiring for the standard layout.

The package exports createFeedbackCopy, createFeedbackTheme, createFeedbackMetadata, and the related types for deeper customization. mockFeedbackApi and createMockFeatureAvailabilityApi are available for demos and tests; they are not required when the host supplies real adapters.