@explorer02/cfm-survey-sdk 0.0.1

package/src/surveyProgress/useSurveyProgress.ts

@@ -0,0 +1,42 @@
+import { useState, useEffect, useMemo } from 'react';
+import type { Survey } from '../fetchSurvey/types';
+import type { SubmitAnswers } from '../submitSurvey/types';
+import { countTotalQuestions, countAnsweredQuestions, calculateProgressPercentage } from './utils';
+
+export interface UseSurveyProgressProps {
+  survey?: Survey | null;
+  values?: SubmitAnswers | null;
+  currentPageIndex?: number;
+}
+
+/**
+ * A custom React hook that tracks progress within a survey.
+ * Computes completed question counts, total questions, and percentage completion.
+ *
+ * @param props Configurations holding active survey definition and answer values.
+ * @returns Real-time calculated progress tracking indices.
+ */
+export function useSurveyProgress({ survey, values, currentPageIndex = 0 }: UseSurveyProgressProps) {
+  const [maxVisitedPageIndex, setMaxVisitedPageIndex] = useState(0);
+
+  // Track the highest page index reached so far
+  useEffect(() => {
+    if (currentPageIndex > maxVisitedPageIndex) {
+      setMaxVisitedPageIndex(currentPageIndex);
+    }
+  }, [currentPageIndex, maxVisitedPageIndex]);
+
+  return useMemo(() => {
+    const totalQuestionsCount = countTotalQuestions(survey);
+    const answeredQuestionsCount = countAnsweredQuestions(survey, values, maxVisitedPageIndex);
+    const progressPercentage = calculateProgressPercentage(answeredQuestionsCount, totalQuestionsCount);
+    const isComplete = totalQuestionsCount > 0 && answeredQuestionsCount === totalQuestionsCount;
+
+    return {
+      totalQuestionsCount,
+      answeredQuestionsCount,
+      progressPercentage,
+      isComplete,
+    };
+  }, [survey, values, maxVisitedPageIndex]);
+}

package/src/surveyProgress/utils/index.ts

@@ -0,0 +1 @@
+export * from './progress';

package/src/surveyProgress/utils/progress.ts

@@ -0,0 +1,61 @@
+import type { Survey } from '../../fetchSurvey/types';
+import type { SubmitAnswers } from '../../submitSurvey/types';
+
+/**
+ * Counts the total number of questions present across all pages of the survey.
+ *
+ * @param survey Fully mapped survey data structure.
+ * @returns Total number of questions.
+ */
+export function countTotalQuestions(survey?: Survey | null): number {
+  if (!survey || !Array.isArray(survey.pages)) return 0;
+  return survey.pages.reduce((acc, page) => acc + (page.questions?.length ?? 0), 0);
+}
+
+/**
+ * Counts the number of questions that have been answered by the user.
+ * Only questions that exist in the active survey configuration are counted.
+ *
+ * @param survey Fully mapped survey data structure.
+ * @param values Values map containing active user answers.
+ * @returns Count of completed questions.
+ */
+export function countAnsweredQuestions(
+  survey?: Survey | null,
+  values?: SubmitAnswers | null,
+  maxVisitedPageIndex: number = 0
+): number {
+  if (!survey || !values || !Array.isArray(survey.pages)) return 0;
+
+  let answeredCount = 0;
+  survey.pages.forEach((page, index) => {
+    if (Array.isArray(page.questions)) {
+      if (index < maxVisitedPageIndex) {
+        // All questions on past pages count as completed (required or optional)
+        answeredCount += page.questions.length;
+      } else {
+        // Questions on current or future pages only count if they have been explicitly answered
+        page.questions.forEach(question => {
+          const value = values[question.id];
+          if (value !== undefined && value !== null && value !== '') {
+            answeredCount++;
+          }
+        });
+      }
+    }
+  });
+
+  return answeredCount;
+}
+
+/**
+ * Computes progress percentage as an integer between 0 and 100.
+ *
+ * @param answered Count of answered questions.
+ * @param total Count of total questions.
+ * @returns Progress percentage rounded to the nearest integer.
+ */
+export function calculateProgressPercentage(answered: number, total: number): number {
+  if (total <= 0) return 0;
+  return Math.min(100, Math.max(0, Math.round((answered / total) * 100)));
+}

package/src/surveySDK/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Enum representing all action types supported by the survey SDK dispatcher.
+ */
+export enum ACTIONS {
+  NEXT = 'NEXT',
+  PREVIOUS = 'PREVIOUS',
+  SUBMIT = 'SUBMIT',
+  CHANGE = 'CHANGE',
+}

package/src/surveySDK/types.ts

@@ -0,0 +1,22 @@
+import { ACTIONS } from './constants';
+
+/**
+ * Union type representing all dispatch actions for the survey SDK.
+ */
+export type SurveyAction =
+  | { type: ACTIONS.NEXT | 'NEXT' }
+  | { type: ACTIONS.PREVIOUS | 'PREVIOUS' }
+  | { type: ACTIONS.SUBMIT | 'SUBMIT' }
+  | { type: ACTIONS.CHANGE | 'CHANGE'; payload: { questionId: string; value: string | number } };
+
+/**
+ * Configuration settings for useSurveySDK hook behavior and layout parameters.
+ */
+export type UseSurveySDKProps = {
+  options?: {
+    language?: string;
+    placeholders?: Record<string, string>;
+    debug?: boolean;
+  };
+};
+

package/src/surveySDK/useSurveySDK.ts

@@ -0,0 +1,109 @@
+import { useCallback, useMemo } from 'react';
+import { useFetchSurvey } from '../fetchSurvey/useFetchSurvey';
+import { useSurveyPagination } from '../surveyPagination/useSurveyPagination';
+// remove unused imports eventhough they are used in the code
+import type { Survey, SurveySession } from '../fetchSurvey/useFetchSurvey';
+import type { SubmitAnswers, SubmitResult } from '../submitSurvey/types';
+import { sdkLogger } from '../logger/logger';
+import { ACTIONS } from './constants';
+import type { SurveyAction, UseSurveySDKProps } from './types';
+
+/**
+ * The main entry-point custom React hook for the survey SDK.
+ * Handles fetching survey configurations, active session state, validation,
+ * page pagination, response submission, and user progress tracking.
+ *
+ * @param props Configuration settings for hook behavior and layout parameters.
+ * @returns Unified state structures, submission indicators, and action triggers.
+ */
+export function useSurveySDK({ options }: UseSurveySDKProps = {}) {
+  // Synchronize debug setting
+  sdkLogger.setEnabled(options?.debug ?? false);
+
+  // 1. Fetch survey layout
+  const { survey, session, fetching, fetchError } = useFetchSurvey({
+    language: options?.language,
+    placeholders: options?.placeholders,
+  });
+
+  // 2. Control navigation, validation, and submission
+  const {
+    currentPageIndex,
+    values,
+    validationErrors,
+    currentQuestions,
+    onBack,
+    onNext,
+    onSubmit,
+    onChange,
+    progressPercentage,
+    submitting,
+    submitError,
+    submitData,
+  } = useSurveyPagination({ survey, session });
+
+  // 3. Define the dispatcher
+  const onAction = useCallback(
+    (action: SurveyAction) => {
+      if (action.type === ACTIONS.NEXT && survey && currentPageIndex === survey.pages.length - 1) {
+        action = { type: ACTIONS.SUBMIT };
+      }
+
+      sdkLogger.info(`Action dispatched: ${action.type}`, action);
+      try {
+        switch (action.type) {
+          // constants and types
+          case ACTIONS.NEXT:
+            onNext();
+            break;
+          case ACTIONS.PREVIOUS:
+            onBack();
+            break;
+          case ACTIONS.SUBMIT:
+            onSubmit();
+            break;
+          case ACTIONS.CHANGE:
+            onChange(action.payload.questionId, action.payload.value);
+            break;
+          default:
+            break;
+        }
+      } catch (err) {
+        sdkLogger.error(`Error executing action: ${action.type}`, err);
+      }
+    },
+    [onNext, onBack, onSubmit, onChange, survey, currentPageIndex]
+  );
+
+  // surveyQueryResults
+  // submitSurveyResults
+  // state
+  // onAction
+  return {
+    // 1. Survey Query Namespace
+    surveyQueryResults: {
+      data: survey,
+      error: fetchError,
+      isLoading: fetching,
+    },
+
+    // 2. Response Submission Namespace
+    submitSurveyResults: {
+      data: submitData,
+      error: submitError,
+      isLoading: submitting,
+    },
+
+    // 3. Client-Interactive State Namespace
+    state: {
+      currentPageIndex,
+      currentQuestions,
+      values,
+      validationErrors,
+      progressPercentage,
+    },
+
+    // 4. Action Dispatcher
+    onAction,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}