@rssa-project/study-template 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+MIT License

package/README.md

@@ -0,0 +1,49 @@
+# RSSA Study Template (@rssa-project/study-template)
+
+[![npm version](https://img.shields.io/npm/v/@rssa-project/study-template.svg)](https://www.npmjs.com/package/@rssa-project/study-template)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A React component library providing standard layouts, pages, and hooks for building research studies on the RSSA Platform. It creates a consistent UI and logic flow (consent -> survey -> stimuli -> feedback) across different RSSA studies.
+
+## Installation
+
+```bash
+npm install @rssa-project/study-template
+```
+
+## Quick Start
+
+Wrap your main router with the `RouteWrapper`, ensuring you pass a component map mapping step types to your page components.
+
+```tsx
+import { RouteWrapper, WelcomePage, SurveyPage, FinalPage } from '@rssa-project/study-template';
+import UserCustomPage from './UserCustomPage';
+
+// Map 'step_type' from your study config to React components
+const componentMap = {
+	welcome: WelcomePage,
+	survey: SurveyPage,
+	custom_task: UserCustomPage,
+	completion: FinalPage,
+};
+
+function App() {
+	return (
+		<Router>
+			{/* RouteWrapper handles navigation logic based on study state */}
+			<RouteWrapper componentMap={componentMap} WelcomePage={WelcomePage} />
+		</Router>
+	);
+}
+```
+
+## Core Features
+
+- **Standard Pages**: `ConsentPage`, `SurveyPage`, `MovieRatingPage`, `DemographicsPage`.
+- **Hooks**: `useNextButtonControl`, `useStepCompletion`.
+- **Contexts**: Handles participant state and navigation flow automatically.
+
+## Requirements
+
+- React 18+
+- `@rssa-project/api` (Peer Dependency)

package/dist/App.d.ts

@@ -0,0 +1,2 @@
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/components/CodeInput.d.ts

@@ -0,0 +1,7 @@
+interface CodeInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    length?: number;
+}
+declare const CodeInput: React.FC<CodeInputProps>;
+export default CodeInput;

package/dist/components/ContinueFormModal.d.ts

@@ -0,0 +1,9 @@
+declare const ContinueFormModal: React.FC<{
+    title: string;
+    isOpen: boolean;
+    onClose: () => void;
+    onSubmit: (resumeCode: string) => void;
+    isSubmitting: boolean;
+    submitButtonText: string;
+}>;
+export default ContinueFormModal;

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,15 @@
+import { Component, ErrorInfo, ReactNode } from 'react';
+interface Props {
+    children: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    errorMessage: string;
+}
+declare class ErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+}
+export default ErrorBoundary;

package/dist/components/LoadingText.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+interface LoadingTextProps {
+    text: string;
+}
+declare const LoadingText: React.FC<LoadingTextProps>;
+export default LoadingText;

package/dist/components/PaginatedDataViewer.d.ts

@@ -0,0 +1,9 @@
+interface PaginatedResourceViewerProps<T> {
+    apiResourceTag: string;
+    limit?: number;
+    children: (data: T[], selectedItem: T | null, handleItemClick: (item: T) => void) => React.ReactNode;
+}
+declare const PaginatedResourceViewer: <T extends {
+    id: string;
+}>({ apiResourceTag, limit, children, }: PaginatedResourceViewerProps<T>) => import("react/jsx-runtime").JSX.Element;
+export default PaginatedResourceViewer;

package/dist/components/Select.d.ts

@@ -0,0 +1,7 @@
+declare const Select: ({ onChange, children, placeholder, className, }: {
+    onChange: (value: string | boolean | number | null) => void;
+    children: React.ReactNode[];
+    placeholder?: string;
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default Select;

package/dist/components/TestFeedbackModal.d.ts

@@ -0,0 +1,10 @@
+import { StudyStep } from '../types/rssa.types';
+import { ToastType } from './TestModeToast';
+interface TestFeedbackModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    studyStep?: StudyStep;
+    onShowToast: (message: string, type: ToastType) => void;
+}
+declare const TestFeedbackModal: React.FC<TestFeedbackModalProps>;
+export default TestFeedbackModal;

package/dist/components/TestModeConfirmation.d.ts

@@ -0,0 +1,7 @@
+interface TestModeConfirmationProps {
+    isOpen: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+declare const TestModeConfirmation: React.FC<TestModeConfirmationProps>;
+export default TestModeConfirmation;

package/dist/components/TestModeIndicator.d.ts

@@ -0,0 +1,6 @@
+import { StudyStep } from '../types/rssa.types';
+interface TestModeIndicatorProps {
+    studyStep?: StudyStep;
+}
+declare const TestModeIndicator: React.FC<TestModeIndicatorProps>;
+export default TestModeIndicator;

package/dist/components/TestModeToast.d.ts

@@ -0,0 +1,10 @@
+export type ToastType = "success" | "error";
+interface TestModeToastProps {
+    show: boolean;
+    message: string;
+    type: ToastType;
+    onClose: () => void;
+    duration?: number;
+}
+declare const TestModeToast: React.FC<TestModeToastProps>;
+export default TestModeToast;

package/dist/components/loadingscreen/LoadingScreen.d.ts

@@ -0,0 +1,7 @@
+interface LoadingScreenProps {
+    loading: boolean;
+    message: string;
+    byline?: string;
+}
+declare const LoadingScreen: React.FC<LoadingScreenProps>;
+export default LoadingScreen;

package/dist/components/moviegallery/MovieCard.d.ts

@@ -0,0 +1,7 @@
+import { MovieDetails, RatedItem } from '../../types/rssa.types';
+declare const MovieCard: ({ movie, userRating, onClick, }: {
+    movie: MovieDetails;
+    userRating: RatedItem | undefined;
+    onClick: () => void;
+}) => import("react/jsx-runtime").JSX.Element;
+export default MovieCard;

package/dist/components/moviegallery/StarRating.d.ts

@@ -0,0 +1,6 @@
+declare const StarRating: ({ initialRating, onRatingChange, maxStars, }: {
+    initialRating: number;
+    onRatingChange: (newRating: number) => void;
+    maxStars: number;
+}) => import("react/jsx-runtime").JSX.Element;
+export default StarRating;

package/dist/components/warningDialog.d.ts

@@ -0,0 +1,12 @@
+interface WarningDialogProps {
+    show: boolean;
+    title: string;
+    message: string;
+    onClose: (show: boolean) => void;
+    confirmCallback?: () => void;
+    confirmText?: string;
+    cancelCallback?: () => void;
+    disableHide?: boolean;
+}
+export declare const WarningDialog: React.FC<WarningDialogProps>;
+export {};

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const STRINGS: {
+    WINDOW_TOO_SMALL: string;
+    STUDY_ERROR: string;
+};
+export declare const customBreakpoints: {
+    xl: number;
+    xxl: number;
+    xxxl: number;
+    xl4: number;
+};
+export declare const RETRY_DELAYS_MS: number[];

package/dist/contexts/NextButtonContext.d.ts

@@ -0,0 +1,12 @@
+import { Dispatch, SetStateAction } from 'react';
+export interface NextButtonControl {
+    label: string;
+    action: () => void;
+    isDisabled: boolean;
+}
+export declare const defaultControl: NextButtonControl;
+export interface NextButtonContextType {
+    setButtonControl: Dispatch<SetStateAction<NextButtonControl>>;
+    buttonControl: NextButtonControl;
+}
+export declare const NextButtonContext: import('react').Context<NextButtonContextType | null>;

package/dist/contexts/NextButtonControlProvider.d.ts

@@ -0,0 +1,3 @@
+export declare const NextButtonControlProvider: ({ children, }: {
+    children: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/contexts/StudyUrlParamsContext.d.ts

@@ -0,0 +1,12 @@
+import { default as React, ReactNode } from 'react';
+interface StudyUrlParams {
+    participantTypeKey: string;
+    externalId: string;
+    isTestMode: boolean;
+}
+export declare const useStudyUrlParams: () => StudyUrlParams;
+export declare const StudyUrlParamsProvider: React.FC<{
+    children: ReactNode;
+    params: StudyUrlParams;
+}>;
+export {};

package/dist/contexts/pageCompletionContext.d.ts

@@ -0,0 +1,4 @@
+import { ReactNode } from 'react';
+export declare const PageCompletionProvider: ({ children, }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/contexts/stepCompletionContext.d.ts

@@ -0,0 +1,4 @@
+import { ReactNode } from 'react';
+export declare const StepCompletionProvider: ({ children, }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/hooks/useDebounce.d.ts

@@ -0,0 +1 @@
+export declare function useDebounce<T>(value: T, delay: number): T;

package/dist/hooks/useNextButtonControl.d.ts

@@ -0,0 +1 @@
+export declare const useNextButtonControl: () => import('..').NextButtonContextType;

package/dist/hooks/usePageCompletion.d.ts

@@ -0,0 +1,7 @@
+interface PageCompletionContextType {
+    isPageComplete: boolean;
+    setIsPageComplete: (isComplete: boolean) => void;
+}
+export declare const PageCompletionContext: import('react').Context<PageCompletionContextType | undefined>;
+export declare const usePageCompletion: () => PageCompletionContextType;
+export {};

package/dist/hooks/useStepCompletion.d.ts

@@ -0,0 +1,7 @@
+interface StepCompletionContextType {
+    isStepComplete: boolean;
+    setIsStepComplete: (isComplete: boolean) => void;
+}
+export declare const StepCompletionContext: import('react').Context<StepCompletionContextType | undefined>;
+export declare const useStepCompletion: () => StepCompletionContextType;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { default as RouteWrapper } from './routes/RouteWrapper';
+export { default as StudyLayout } from './layouts/StudyLayout';
+export { default as LoadingScreen } from './components/loadingscreen/LoadingScreen';
+export { default as ErrorBoundary } from './components/ErrorBoundary';
+export * from './types/rssa.types.ts';
+export * from './types/study.types.ts';
+export * from './hooks/useStepCompletion';
+export * from './hooks/useNextButtonControl';
+export * from './hooks/usePageCompletion';
+export * from './contexts/stepCompletionContext';
+export * from './contexts/NextButtonControlProvider';
+export * from './contexts/NextButtonContext';
+export * from './contexts/pageCompletionContext';
+export { default as SurveyPage } from './pages/SurveyPage';
+export { default as SurveyTemplate } from './layouts/templates/SurveyTemplate';
+export { default as WelcomePage } from './pages/WelcomePage';
+export { default as ConsentPage } from './pages/ConsentPage';
+export { default as MovieRatingPage } from './pages/MovieRatingPage';
+export { default as MovieCard } from './components/moviegallery/MovieCard';
+export { default as StarRating } from './components/moviegallery/StarRating';
+export { default as DemographicsPage } from './pages/DemographicsPage';
+export { default as FeedbackPage } from './pages/FeedbackPage';
+export { default as LoadingText } from './components/LoadingText';
+export { default as FinalPage } from './pages/FinalPage';
+export { WarningDialog } from './components/warningDialog';
+export * from './hooks/useDebounce';

package/dist/layouts/StudyFooter.d.ts

@@ -0,0 +1,2 @@
+export declare const Footer: React.FC;
+export default Footer;

package/dist/layouts/StudyHeader.d.ts

@@ -0,0 +1,5 @@
+export declare const Header: React.FC<{
+    title: string;
+    content: string;
+}>;
+export default Header;

package/dist/layouts/StudyLayout.d.ts

@@ -0,0 +1,6 @@
+import { StudyStep } from '../types/rssa.types';
+interface StudyLayoutProps {
+    stepApiData: StudyStep | undefined;
+}
+declare const StudyLayout: ({ stepApiData }: StudyLayoutProps) => import("react/jsx-runtime").JSX.Element;
+export default StudyLayout;

package/dist/layouts/WelcomeFooter.d.ts

@@ -0,0 +1,8 @@
+export declare const WelcomeFooter: React.FC<{
+    onStudyStart: () => void;
+    onStudyContinue: (showForm: boolean) => void;
+    disabled?: boolean;
+    text?: string;
+    loading?: false;
+}>;
+export default WelcomeFooter;

package/dist/layouts/templates/ContentBlock.d.ts

@@ -0,0 +1,7 @@
+import { PageContent } from '../../types/rssa.types';
+interface ContentBlockProps {
+    content: PageContent;
+    onComplete: (contentId: string) => void;
+}
+declare const ContentBlock: React.FC<ContentBlockProps>;
+export default ContentBlock;

package/dist/layouts/templates/ItemBlock.d.ts

@@ -0,0 +1,11 @@
+import { ScaleLevel, SurveyConstructItem, SurveyItemResponse } from '../../types/rssa.types';
+interface ItemBlockProps {
+    contextTag: string;
+    pageId: string;
+    item: SurveyConstructItem;
+    initialResponse: SurveyItemResponse | undefined;
+    scaleLevels: ScaleLevel[];
+    onSelected: (itemId: string) => void;
+}
+declare const ItemBlock: React.FC<ItemBlockProps>;
+export default ItemBlock;

package/dist/layouts/templates/SurveyTemplate.d.ts

@@ -0,0 +1,6 @@
+import { SurveyPageType } from '../../types/rssa.types';
+interface SurveyTemplateProps {
+    surveyPage: SurveyPageType;
+}
+declare const SurveyTemplate: React.FC<SurveyTemplateProps>;
+export default SurveyTemplate;

package/dist/pages/ConsentPage.d.ts

@@ -0,0 +1,21 @@
+export interface BaseParticipant {
+    participant_type_key: string;
+    external_id: string;
+    current_step_id: string;
+    current_page_id?: string | null;
+}
+export interface ParticipantTokenObject {
+    resume_code: string;
+    token: string;
+}
+interface ConsentPageProps {
+    children: React.ReactNode;
+    participantTypeKey?: string;
+    participantTypeId?: string;
+    externalId?: string;
+    onConsentSuccess?: (token: string, resumeCode: string) => void;
+    title?: string;
+    itemTitle?: string;
+}
+declare const ConsentPage: React.FC<ConsentPageProps>;
+export default ConsentPage;

package/dist/pages/DemographicsPage.d.ts

@@ -0,0 +1,2 @@
+declare const DemographicsPage: React.FC;
+export default DemographicsPage;

package/dist/pages/FeedbackPage.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+export type Feedback = {
+    feedback_text: string;
+    feedback_type: string;
+    feedback_category: string;
+    study_step_id: string;
+    context_tag: string;
+};
+export type TextResponsePayload = {
+    study_step_id: string;
+    study_step_page_id?: string;
+    context_tag: string;
+    response_text: string;
+};
+declare const FeedbackPage: React.FC;
+export default FeedbackPage;

package/dist/pages/FinalPage.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+declare const FinalPage: React.FC;
+export default FinalPage;

package/dist/pages/MovieRatingPage.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+interface MovieRatingPageProps {
+    minRatingCount?: number;
+    itemsPerPage?: number;
+}
+declare const MovieRatingPage: React.FC<MovieRatingPageProps>;
+export default MovieRatingPage;

package/dist/pages/StudyExitPage.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+declare const StudyExitPage: React.FC;
+export default StudyExitPage;

package/dist/pages/SurveyPage.d.ts

@@ -0,0 +1,2 @@
+declare const SurveyPage: React.FC;
+export default SurveyPage;

package/dist/pages/WelcomePage.d.ts

@@ -0,0 +1,18 @@
+export interface ResumePayload {
+    resume_code: string;
+}
+export interface ResumeResponse {
+    current_step_id: string;
+    current_page_id: string;
+    token: string;
+}
+interface WelcomePageProps {
+    isStudyReady?: boolean;
+    onStudyStart?: () => void;
+    title?: string;
+    subtitle?: string;
+    ContentComponent?: React.FC;
+    children?: React.ReactNode;
+}
+declare const WelcomePage: React.FC<WelcomePageProps>;
+export default WelcomePage;