spaps-issue-reporting-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.0] - 2026-03-29
+
+- Added the first shared React issue-reporting package for SPAPS consumers.
+- Shipped the floating entrypoint, history popover, report mode, and create/edit/reply modal flows.
+- Added package tests covering eligibility gating, create flow, and hydrated edit/reply behavior.

package/README.md

@@ -0,0 +1,69 @@
+# spaps-issue-reporting-react
+
+Shared React issue-reporting UI for SPAPS-powered apps. This package owns the floating bug entrypoint, history popover, report-mode state, and create/edit/reply modal flows while leaving each app in control of eligibility and reportable surface registration.
+
+## Metadata
+- `package_name`: `spaps-issue-reporting-react`
+- `latest_version`: `0.1.0`
+- `minimum_runtime`: `Node.js >=18.0.0`
+- `api_base_url`: `https://api.sweetpotato.dev`
+
+## Installation
+
+```bash
+npm install spaps-issue-reporting-react
+```
+
+Required peers:
+
+```bash
+npm install react react-dom @tanstack/react-query
+```
+
+## Usage
+
+```tsx
+import {
+  FloatingIssueReportButton,
+  IssueReportingProvider,
+  useReportMode,
+} from "spaps-issue-reporting-react";
+import { spapsClient } from "./spapsClient";
+
+function AppShell() {
+  return (
+    <IssueReportingProvider
+      client={spapsClient}
+      isEligible={true}
+      reporterRoleHint="practitioner"
+    >
+      <Routes />
+      <FloatingIssueReportButton />
+    </IssueReportingProvider>
+  );
+}
+
+function ReportableCard() {
+  const reportMode = useReportMode();
+
+  return (
+    <section
+      className={reportMode?.isReportMode ? "ring-2 ring-amber-400" : undefined}
+      onClick={() => reportMode?.selectPanel("Protocol Widget")}
+    >
+      ...
+    </section>
+  );
+}
+```
+
+## What The App Owns
+
+- Local eligibility logic such as `practitioner` vs patient feature flags.
+- Reportable target registration via `useReportMode`, `ReportableSection`, or equivalent wrappers.
+- Tailwind content configuration so package classes are included in the host build.
+- Any app-specific copy overrides passed through the provider.
+
+## Related Docs
+
+- [CHANGELOG.md](./CHANGELOG.md)

package/dist/index.d.mts

@@ -0,0 +1,343 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import * as spaps_types from 'spaps-types';
+import { IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, UpdateIssueReportRequest, ReplyIssueReportRequest } from 'spaps-types';
+export { CreateIssueReportRequest, IssueReport, IssueReportListResult, IssueReportStatus, IssueReportStatusResult, ReplyIssueReportRequest, UpdateIssueReportRequest } from 'spaps-types';
+import * as _tanstack_query_core from '@tanstack/query-core';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+interface IssueReportingClient {
+    issueReporting: {
+        getStatus: () => Promise<IssueReportStatusResult>;
+        list: (params?: {
+            status?: IssueReportStatus;
+            limit?: number;
+            offset?: number;
+        }) => Promise<IssueReportListResult>;
+        get: (issueReportId: string) => Promise<IssueReport>;
+        create: (payload: CreateIssueReportRequest) => Promise<IssueReport>;
+        update: (issueReportId: string, payload: UpdateIssueReportRequest) => Promise<IssueReport>;
+        reply: (issueReportId: string, payload: ReplyIssueReportRequest) => Promise<IssueReport>;
+    };
+}
+interface ReportableTargetDescriptor {
+    componentKey: string;
+    componentLabel?: string;
+    surfaceRef?: string | null;
+    metadata?: Record<string, unknown>;
+}
+type ReportableInput = string | ReportableTargetDescriptor;
+type IssueHistoryFilter = "all" | "open" | "closed";
+interface IssueReportingCopy {
+    entryAriaLabel: string;
+    popoverTitle: string;
+    reportNewAction: string;
+    filtersAll: string;
+    filtersOpen: string;
+    filtersClosed: string;
+    historyHelpText: string;
+    historyLoading: string;
+    historyLoadFailed: string;
+    emptyAll: string;
+    emptyOpen: string;
+    emptyClosed: string;
+    reportModeTitle: string;
+    reportModeDescription: string;
+    reportModeCancelAction: string;
+    createTitlePrefix: string;
+    editTitlePrefix: string;
+    replyTitlePrefix: string;
+    createDescriptionPrefix: string;
+    editDescription: string;
+    replyDescription: string;
+    notePlaceholder: string;
+    noteMinimumSuffix: string;
+    keyboardShortcutHint: string;
+    originalIssueLabel: string;
+    cancelAction: string;
+    submitAction: string;
+    submittingAction: string;
+    editAction: string;
+    replyAction: string;
+    hydrateLoading: string;
+    hydrateFailed: string;
+    retryAction: string;
+}
+interface IssueReportingProviderProps {
+    client: IssueReportingClient;
+    isEligible: boolean;
+    reporterRoleHint?: string;
+    getPageUrl?: () => string;
+    copy?: Partial<IssueReportingCopy>;
+    children: ReactNode;
+}
+interface FloatingIssueReportButtonProps {
+    className?: string;
+    positionClassName?: string;
+}
+
+declare function FloatingIssueReportButton({ className, positionClassName, }: FloatingIssueReportButtonProps): react_jsx_runtime.JSX.Element | null;
+declare function ReportableSection({ reportableName, children, className, as: Component, }: {
+    reportableName: ReportableInput;
+    children: React__default.ReactNode;
+    className?: string;
+    as?: keyof JSX.IntrinsicElements;
+}): react_jsx_runtime.JSX.Element;
+
+type ModalMode = "create" | "edit" | "reply";
+type ResolvedTarget = {
+    component_key: string;
+    component_label: string;
+    page_url: string;
+    surface_ref: string | null;
+    metadata: Record<string, unknown>;
+};
+type ModalState = {
+    isOpen: boolean;
+    mode: ModalMode;
+    issueReportId: string | null;
+    issue: IssueReport | null;
+    target: ResolvedTarget | null;
+    error: string | null;
+    isHydrating: boolean;
+};
+type IssueReportingContextValue = {
+    client: IssueReportingProviderProps["client"];
+    isEligible: boolean;
+    reporterRoleHint?: string;
+    copy: IssueReportingCopy;
+    isReportMode: boolean;
+    enterReportMode: () => void;
+    cancelReportMode: () => void;
+    selectPanel: (target: ReportableInput) => void;
+    isPopoverOpen: boolean;
+    openPopover: () => void;
+    closePopover: () => void;
+    modalState: ModalState;
+    closeModal: () => void;
+    openExistingIssueModal: (issueReportId: string, mode: Exclude<ModalMode, "create">) => Promise<void>;
+    retryModalHydration: () => Promise<void>;
+};
+declare const defaultIssueReportingCopy: IssueReportingCopy;
+declare const issueReportingKeys: {
+    all: readonly ["spaps-issue-reporting"];
+    status: () => readonly ["spaps-issue-reporting", "status"];
+    history: () => readonly ["spaps-issue-reporting", "history"];
+    detail: (issueReportId: string) => readonly ["spaps-issue-reporting", "detail", string];
+};
+declare function isOpenIssueStatus(status: IssueReportStatus): boolean;
+declare function isClosedIssueStatus(status: IssueReportStatus): boolean;
+declare function filterIssueReports(issues: IssueReport[], filter: IssueHistoryFilter): IssueReport[];
+declare function getIssueStatusBadgeLabel(status: IssueReportStatus): string;
+declare function getIssueStatusClassName(status: IssueReportStatus): string;
+declare function getEntryPointState(status?: {
+    has_open: boolean;
+    has_recent_resolved: boolean;
+} | null): "open" | "recent_resolved" | "neutral";
+declare function getEntryPointClassName(state: "open" | "recent_resolved" | "neutral"): string;
+declare function getIssueNoteLengthMessage(note: string, copy: IssueReportingCopy): string;
+declare function useIssueReporting(): IssueReportingContextValue;
+declare function useIssueReportingStatus(): _tanstack_react_query.UseQueryResult<spaps_types.IssueReportStatusResult, Error>;
+declare function useIssueReportingHistory(filter?: IssueHistoryFilter): {
+    items: IssueReport[];
+    total: number;
+    data: spaps_types.IssueReportListResult;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+} | {
+    items: IssueReport[];
+    total: number;
+    data: spaps_types.IssueReportListResult;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+} | {
+    items: IssueReport[];
+    total: number;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+} | {
+    items: IssueReport[];
+    total: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+} | {
+    items: IssueReport[];
+    total: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+} | {
+    items: IssueReport[];
+    total: number;
+    data: spaps_types.IssueReportListResult;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<spaps_types.IssueReportListResult, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<spaps_types.IssueReportListResult>;
+};
+declare function useIssueReportingMutations(): {
+    createMutation: _tanstack_react_query.UseMutationResult<IssueReport, Error, {
+        target: ResolvedTarget;
+        note: string;
+        reporter_role_hint?: string;
+    }, unknown>;
+    updateMutation: _tanstack_react_query.UseMutationResult<IssueReport, Error, {
+        issueReportId: string;
+        note: string;
+    }, unknown>;
+    replyMutation: _tanstack_react_query.UseMutationResult<IssueReport, Error, {
+        issueReportId: string;
+        note: string;
+        reporterRoleHint?: string;
+    }, unknown>;
+};
+declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, getPageUrl, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ReportModeContextValue {
+    isReportMode: boolean;
+    selectPanel: (target: ReportableInput) => void;
+    cancelReportMode: () => void;
+}
+declare const ReportModeContext: React.Context<ReportModeContextValue | null>;
+declare function useReportMode(): ReportModeContextValue | null;
+
+export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };