@explorer02/cfm-survey-sdk 0.0.1 → 0.0.2

package/src/surveyPagination/actions/useOnSubmit.ts

@@ -1,137 +0,0 @@
-import { useCallback } from 'react';
-import { logSubmitInitiated, logPaginationSubmitError, logScrollWarning } from '../logger/navigationLogger';
-import {
-  logValidationPassedSubmit,
-  logValidationErrorSubmit,
-  logValidationFailedSubmit,
-} from '../logger/validationLogger';
-import { trackValidationError } from '../telemetry/pageTelemetry';
-import { trackSessionSummary } from '../telemetry/sessionTelemetry';
-import { validateAllPages, findQuestionElement } from '../utils';
-import type { SurveyPaginationContext } from '../types';
-
-export function useOnSubmit(context: SurveyPaginationContext) {
-  const {
-    survey,
-    pages,
-    values,
-    submit,
-    currentPageIndex,
-    setCurrentPageIndex,
-    setValidationErrors,
-    trackPageTime,
-    trackOptionalSkips,
-    checkBacktrackChanges,
-    totalQuestionsCount,
-    paginationRefs,
-  } = context;
-
-  return useCallback(async () => {
-    if (!survey) return;
-
-    logSubmitInitiated();
-    let validation = null;
-    try {
-      validation = validateAllPages(pages, values, survey.language);
-      if (!validation) {
-        logValidationPassedSubmit();
-      }
-    } catch (err) {
-      logValidationFailedSubmit(err);
-    }
-
-    const refs = paginationRefs.current;
-
-    if (validation) {
-      logValidationErrorSubmit(validation);
-
-      // Track validation error attempt
-      const attempt = (refs.validationAttempt[validation.errorPageIndex] || 0) + 1;
-      refs.validationAttempt[validation.errorPageIndex] = attempt;
-      refs.validationErrorsCount += 1;
-      refs.validationHistory.push({
-        pageIndex: validation.errorPageIndex,
-        errors: validation.errors,
-        attemptNumber: attempt,
-      });
-
-      trackValidationError(validation.errorPageIndex, validation.errors, attempt);
-
-      setValidationErrors(validation.errors);
-      setCurrentPageIndex(validation.errorPageIndex);
-      setTimeout(() => {
-        try {
-          const element = findQuestionElement(validation.firstErrorId);
-          if (element) {
-            element.scrollIntoView({ behavior: 'smooth', block: 'center' });
-          }
-        } catch (err) {
-          logScrollWarning('Failed to scroll validation error element into view', err);
-        }
-      }, 100);
-      return;
-    }
-
-    setValidationErrors({});
-
-    // Clear validation attempt on success
-    delete refs.validationAttempt[currentPageIndex];
-
-    // Track final page time and skipped questions
-    trackPageTime(currentPageIndex);
-    trackOptionalSkips(currentPageIndex);
-    checkBacktrackChanges(currentPageIndex);
-
-    try {
-      const result = await submit(values);
-      if (result && result.success) {
-        if (!refs.hasLoggedSummary) {
-          const totalDurationMs = performance.now() - refs.sessionStartTime;
-
-          // Calculate skipped optional questions
-          const skippedQuestionIds: string[] = [];
-          pages.forEach(page => {
-            page.questions.forEach(question => {
-              if (!question.required) {
-                const val = values[question.id];
-                if (val === undefined || val === '') {
-                  skippedQuestionIds.push(question.id);
-                }
-              }
-            });
-          });
-          const skippedQuestionsCount = skippedQuestionIds.length;
-
-          trackSessionSummary(
-            true,
-            refs.maxVisitedPageIndex,
-            totalDurationMs,
-            totalQuestionsCount,
-            totalQuestionsCount - skippedQuestionsCount,
-            skippedQuestionsCount,
-            skippedQuestionIds,
-            refs.validationErrorsCount,
-            refs.backtrackCount,
-            refs.validationHistory
-          );
-          refs.hasLoggedSummary = true;
-        }
-      }
-    } catch (err) {
-      logPaginationSubmitError(err);
-    }
-  }, [
-    survey,
-    pages,
-    values,
-    submit,
-    currentPageIndex,
-    setCurrentPageIndex,
-    setValidationErrors,
-    trackPageTime,
-    trackOptionalSkips,
-    checkBacktrackChanges,
-    totalQuestionsCount,
-    paginationRefs,
-  ]);
-}

package/src/surveyPagination/dispatchers/index.ts

@@ -1,3 +0,0 @@
-export { useCheckBacktrackChanges } from './useCheckBacktrackChanges';
-export { useTrackOptionalSkips } from './useTrackOptionalSkips';
-export { useTrackPageTime } from './useTrackPageTime';

package/src/surveyPagination/dispatchers/useCheckBacktrackChanges.ts

@@ -1,35 +0,0 @@
-import { useCallback, RefObject } from 'react';
-import type { SurveyPageData } from '../../fetchSurvey/types';
-import type { SubmitAnswers } from '../../submitSurvey/types';
-import { trackBacktrackRevisited } from '../telemetry/sessionTelemetry';
-import type { SurveyPaginationRefs } from '../types';
-
-export function useCheckBacktrackChanges(
-  pages: SurveyPageData[],
-  values: SubmitAnswers,
-  paginationRefs: RefObject<SurveyPaginationRefs>
-) {
-  return useCallback(
-    (pageIndex: number) => {
-      const backtrackInfo = paginationRefs.current.backtrackSnapshots[pageIndex];
-      if (backtrackInfo) {
-        const pageQuestions = pages[pageIndex]?.questions ?? [];
-        const changedAnswers: Record<string, { oldValue: any; newValue: any }> = {};
-        let hasChanges = false;
-        pageQuestions.forEach(q => {
-          const oldVal = backtrackInfo.snapshot[q.id];
-          const newVal = values[q.id];
-          if (oldVal !== newVal) {
-            changedAnswers[q.id] = { oldValue: oldVal ?? null, newValue: newVal ?? null };
-            hasChanges = true;
-          }
-        });
-        if (hasChanges) {
-          trackBacktrackRevisited(backtrackInfo.fromPageIndex, pageIndex, changedAnswers);
-        }
-        delete paginationRefs.current.backtrackSnapshots[pageIndex];
-      }
-    },
-    [pages, values, paginationRefs]
-  );
-}

package/src/surveyPagination/dispatchers/useTrackOptionalSkips.ts

@@ -1,21 +0,0 @@
-import { useCallback } from 'react';
-import type { SurveyPageData } from '../../fetchSurvey/types';
-import type { SubmitAnswers } from '../../submitSurvey/types';
-import { trackOptionalQuestionSkipped } from '../telemetry/sessionTelemetry';
-
-export function useTrackOptionalSkips(pages: SurveyPageData[], values: SubmitAnswers) {
-  return useCallback(
-    (pageIndex: number) => {
-      const pageQuestions = pages[pageIndex]?.questions ?? [];
-      pageQuestions.forEach(question => {
-        const isOptional = !question.required;
-        const val = values[question.id];
-        const hasNoValue = val === undefined || val === '';
-        if (isOptional && hasNoValue) {
-          trackOptionalQuestionSkipped(question.id, pageIndex);
-        }
-      });
-    },
-    [pages, values]
-  );
-}

package/src/surveyPagination/dispatchers/useTrackPageTime.ts

@@ -1,13 +0,0 @@
-import { useCallback, RefObject } from 'react';
-import { trackPageTimeSpent } from '../telemetry/pageTelemetry';
-import type { SurveyPaginationRefs } from '../types';
-
-export function useTrackPageTime(paginationRefs: RefObject<SurveyPaginationRefs>) {
-  return useCallback(
-    (pageIndex: number) => {
-      const durationMs = performance.now() - paginationRefs.current.pageStartTime;
-      trackPageTimeSpent(pageIndex, durationMs);
-    },
-    [paginationRefs]
-  );
-}

package/src/surveyPagination/effects/index.ts

@@ -1,2 +0,0 @@
-export { useResetPageStartTime } from './useResetPageStartTime';
-export { useTrackMaxVisitedPage } from './useTrackMaxVisitedPage';

package/src/surveyPagination/effects/useResetPageStartTime.ts

@@ -1,10 +0,0 @@
-import { useEffect } from 'react';
-import type { SurveyPaginationContext } from '../types';
-
-export function useResetPageStartTime(context: SurveyPaginationContext): void {
-  const { currentPageIndex, paginationRefs } = context;
-
-  useEffect(() => {
-    paginationRefs.current.pageStartTime = performance.now();
-  }, [currentPageIndex, paginationRefs]);
-}

package/src/surveyPagination/effects/useTrackMaxVisitedPage.ts

@@ -1,12 +0,0 @@
-import { useEffect } from 'react';
-import type { SurveyPaginationContext } from '../types';
-
-export function useTrackMaxVisitedPage(context: SurveyPaginationContext): void {
-  const { currentPageIndex, paginationRefs } = context;
-
-  useEffect(() => {
-    if (currentPageIndex > paginationRefs.current.maxVisitedPageIndex) {
-      paginationRefs.current.maxVisitedPageIndex = currentPageIndex;
-    }
-  }, [currentPageIndex, paginationRefs]);
-}

package/src/surveyPagination/logger/navigationLogger.ts

@@ -1,25 +0,0 @@
-import { sdkLogger } from '../../logger/logger';
-
-export function logChangeAnswer(questionId: string, value: string | number): void {
-  sdkLogger.info(`Answer changed for question: ${questionId}`, { value });
-}
-
-export function logScrollWarning(msg: string, err: any): void {
-  sdkLogger.warn(msg, err);
-}
-
-export function logSubmitInitiated(): void {
-  sdkLogger.info('Initiating survey submission...');
-}
-
-export function logBackNavigation(currentIndex: number): void {
-  sdkLogger.info(`Navigating back from page index: ${currentIndex}`);
-}
-
-export function logNextNavigation(currentIndex: number): void {
-  sdkLogger.info(`Navigating next from page index: ${currentIndex}`);
-}
-
-export function logPaginationSubmitError(err: any): void {
-  sdkLogger.error('Error encountered during pagination submit trigger', err);
-}

package/src/surveyPagination/logger/validationLogger.ts

@@ -1,17 +0,0 @@
-import { sdkLogger } from '../../logger/logger';
-
-export function logValidationPassedSubmit(): void {
-  sdkLogger.success('Survey validation passed on submit');
-}
-
-export function logValidationErrorSubmit(validation: any): void {
-  sdkLogger.warn('Full survey validation failed on submit', { validation });
-}
-
-export function logValidationFailedSubmit(err: any): void {
-  sdkLogger.error('Failed to run survey validation on submit', err);
-}
-
-export function logValidationErrorPage(errors: any): void {
-  sdkLogger.warn('Page validation failed', { errors });
-}

package/src/surveyPagination/telemetry/pageTelemetry.ts

@@ -1,22 +0,0 @@
-import { trackEvent } from '../../analytics/analyticsTracker';
-
-export function trackPageTimeSpent(pageIndex: number, durationMs: number): void {
-  trackEvent({
-    eventName: 'page_time_spent',
-    metadata: {
-      pageIndex,
-      durationMs,
-    },
-  });
-}
-
-export function trackValidationError(pageIndex: number, errors: Record<string, string>, attemptNumber: number): void {
-  trackEvent({
-    eventName: 'validation_error',
-    metadata: {
-      pageIndex,
-      errors,
-      attemptNumber,
-    },
-  });
-}

package/src/surveyPagination/telemetry/sessionTelemetry.ts

@@ -1,55 +0,0 @@
-import { trackEvent } from '../../analytics/analyticsTracker';
-
-export function trackSessionSummary(
-  completed: boolean,
-  maxVisitedPageIndex: number,
-  totalDurationMs: number,
-  totalQuestionsCount: number,
-  answeredQuestionsCount: number,
-  skippedQuestionsCount: number,
-  skippedQuestionIds: string[],
-  validationErrorsCount: number,
-  backtrackCount: number,
-  validationHistory: Array<{
-    pageIndex: number;
-    errors: Record<string, string>;
-    attemptNumber: number;
-  }>
-): void {
-  trackEvent({
-    eventName: 'survey_session_summary',
-    metadata: {
-      maxVisitedPageIndex,
-      totalDurationMs,
-      completed,
-      totalQuestionsCount,
-      answeredQuestionsCount,
-      skippedQuestionsCount,
-      skippedQuestionIds,
-      validationErrorsCount,
-      backtrackCount,
-      validationHistory,
-    },
-  });
-}
-
-export function trackOptionalQuestionSkipped(questionId: string, pageIndex: number): void {
-  trackEvent({
-    eventName: 'optional_question_skipped',
-    metadata: {
-      questionId,
-      pageIndex,
-    },
-  });
-}
-
-export function trackBacktrackRevisited(fromPageIndex: number, toPageIndex: number, changedAnswers: any): void {
-  trackEvent({
-    eventName: 'backtrack_revisited',
-    metadata: {
-      fromPageIndex,
-      toPageIndex,
-      changedAnswers,
-    },
-  });
-}

package/src/surveyPagination/types.ts

@@ -1,42 +0,0 @@
-import type { Dispatch, SetStateAction, RefObject } from 'react';
-import type { Survey, SurveySession, SurveyPageData } from '../fetchSurvey/types';
-import type { SubmitAnswers } from '../submitSurvey/types';
-
-export type SurveyPaginationRefs = {
-  pageStartTime: number;
-  sessionStartTime: number;
-  maxVisitedPageIndex: number;
-  validationAttempt: Record<number, number>;
-  backtrackSnapshots: Record<number, { fromPageIndex: number; snapshot: Record<string, any> }>;
-  hasLoggedSummary: boolean;
-  validationErrorsCount: number;
-  backtrackCount: number;
-  validationHistory: Array<{
-    pageIndex: number;
-    errors: Record<string, string>;
-    attemptNumber: number;
-  }>;
-}
-
-export type SurveyPaginationContext = {
-  survey?: Survey | null;
-  session?: SurveySession | null;
-  pages: SurveyPageData[];
-  currentPageIndex: number;
-  setCurrentPageIndex: Dispatch<SetStateAction<number>>;
-  values: SubmitAnswers;
-  setValues: Dispatch<SetStateAction<SubmitAnswers>>;
-  validationErrors: Record<string, string>;
-  setValidationErrors: Dispatch<SetStateAction<Record<string, string>>>;
-  paginationRefs: RefObject<SurveyPaginationRefs>;
-  trackPageTime: (pageIndex: number) => void;
-  trackOptionalSkips: (pageIndex: number) => void;
-  checkBacktrackChanges: (pageIndex: number) => void;
-  submit: (values: SubmitAnswers) => Promise<any>;
-  totalQuestionsCount: number;
-}
-
-export type UseSurveyPaginationProps = {
-  survey?: Survey | null;
-  session?: SurveySession | null;
-};

package/src/surveyPagination/useSurveyPagination.ts

@@ -1,109 +0,0 @@
-import { useState, useRef } from 'react';
-import type { Survey, SurveySession } from '../fetchSurvey/useFetchSurvey';
-import type { SubmitAnswers } from '../submitSurvey/types';
-import { useSubmitResponse } from '../submitSurvey/useSubmitResponse';
-import { useSurveyProgress } from '../surveyProgress/useSurveyProgress';
-import {
-  useResetPageStartTime,
-  useTrackMaxVisitedPage,
-} from './effects';
-import { useOnBack, useOnChange, useOnNext, useOnSubmit } from './actions';
-import { useTrackPageTime, useTrackOptionalSkips, useCheckBacktrackChanges } from './dispatchers';
-import type { SurveyPaginationRefs, SurveyPaginationContext, UseSurveyPaginationProps } from './types';
-
-/**
- * A custom React hook that manages survey pagination state, user answers,
- * validation errors, and page-relative scrolling interactions.
- *
- * @param props The configuration properties holding survey details and session tokens.
- * @returns An object containing page states, validation statuses, and interactive callbacks.
- */
-export function useSurveyPagination({ survey, session }: UseSurveyPaginationProps) {
-  const [values, setValues] = useState<SubmitAnswers>({});
-  const [validationErrors, setValidationErrors] = useState<Record<string, string>>({});
-  const [currentPageIndex, setCurrentPageIndex] = useState(0);
-
-  const pages = survey?.pages ?? [];
-  const currentPage = pages[currentPageIndex];
-  const currentQuestions = currentPage?.questions ?? [];
-
-  // Integrate response submission
-  const { submit, data: submitData, loading: submitting, error: submitError } = useSubmitResponse(session, survey);
-
-  // Integrate progress tracking
-  const { progressPercentage, totalQuestionsCount, answeredQuestionsCount, isComplete } = useSurveyProgress({
-    survey,
-    values,
-    currentPageIndex,
-  });
-
-  // Consolidated Analytics & Pagination Refs
-  const paginationRefs = useRef<SurveyPaginationRefs>({
-    pageStartTime: performance.now(),
-    sessionStartTime: performance.now(),
-    maxVisitedPageIndex: 0,
-    validationAttempt: {},
-    backtrackSnapshots: {},
-    hasLoggedSummary: false,
-    validationErrorsCount: 0,
-    backtrackCount: 0,
-    validationHistory: [],
-  });
-
-  // Instantiate dispatcher hooks
-  const trackPageTime = useTrackPageTime(paginationRefs);
-  const trackOptionalSkips = useTrackOptionalSkips(pages, values);
-  const checkBacktrackChanges = useCheckBacktrackChanges(pages, values, paginationRefs);
-
-  // Construct context object grouping parameters, functions, and state
-  const context: SurveyPaginationContext = {
-    survey,
-    session,
-    pages,
-    currentPageIndex,
-    setCurrentPageIndex,
-    values,
-    setValues,
-    validationErrors,
-    setValidationErrors,
-    paginationRefs,
-    trackPageTime,
-    trackOptionalSkips,
-    checkBacktrackChanges,
-    submit,
-    totalQuestionsCount,
-  };
-
-  // Call modular effects
-  useTrackMaxVisitedPage(context);
-
-  useResetPageStartTime(context);
-
-  // Call modular actions
-  const onChange = useOnChange(context);
-
-  const onBack = useOnBack(context);
-
-  const onSubmit = useOnSubmit(context);
-
-  const onNext = useOnNext(context, onSubmit);
-
-  return {
-    currentPageIndex,
-    values,
-    validationErrors,
-    currentQuestions,
-    pages,
-    onChange,
-    onBack,
-    onNext,
-    onSubmit,
-    progressPercentage,
-    totalQuestionsCount,
-    answeredQuestionsCount,
-    isComplete,
-    submitting,
-    submitError,
-    submitData,
-  };
-}

package/src/surveyPagination/utils/index.ts

@@ -1,2 +0,0 @@
-export * from './validation';
-export * from './scroll';

package/src/surveyPagination/utils/scroll.ts

@@ -1,62 +0,0 @@
-import type { SurveyPageData } from '../../fetchSurvey/types';
-import { logScrollWarning } from '../logger/navigationLogger';
-
-/**
- * Resolves the DOM element corresponding to a given question ID.
- * Expects the developer to assign standard ID attributes matching the question identifier.
- *
- * @param questionId The unique identifier of the target question.
- * @returns The resolved HTMLElement, or null if server-side rendering or element not found.
- */
-export function findQuestionElement(questionId: string): HTMLElement | null {
-  if (typeof document === 'undefined') return null;
-  return document.getElementById(questionId) || null;
-}
-
-/**
- * Resolves the logical survey container boundary wrapping the question.
- * Looks for semantic HTML containers (main, form) or defaults to parent hierarchy.
- *
- * @param firstQuestionEl The element of the first question on the active page.
- * @returns The resolved survey container element.
- */
-export function findSurveyContainer(firstQuestionEl: HTMLElement): HTMLElement {
-  return (
-    firstQuestionEl.closest('main') ||
-    firstQuestionEl.closest('form') ||
-    firstQuestionEl.parentElement ||
-    firstQuestionEl
-  );
-}
-
-/**
- * Scrolls the viewport to the top of the survey container for the specified page index.
- *
- * @param pages List of survey pages.
- * @param pageIndex The target page index to navigate and scroll to.
- */
-export function scrollToFirstQuestionOfPage(pages: SurveyPageData[], pageIndex: number): void {
-  try {
-    const targetPage = pages[pageIndex];
-    const firstQuestion = targetPage?.questions?.[0];
-    if (firstQuestion) {
-      setTimeout(() => {
-        try {
-          const questionEl = findQuestionElement(firstQuestion.id);
-          if (questionEl) {
-            const surveyContainer = findSurveyContainer(questionEl);
-            surveyContainer.scrollIntoView({ behavior: 'smooth', block: 'start' });
-          } else {
-            window.scrollTo({ top: 0, behavior: 'smooth' });
-          }
-        } catch (err) {
-          logScrollWarning('Failed to scroll page first question into view', err);
-        }
-      }, 50);
-    } else {
-      window.scrollTo({ top: 0, behavior: 'smooth' });
-    }
-  } catch (err) {
-    logScrollWarning('Failed to trigger scroll navigation', err);
-  }
-}

package/src/surveyPagination/utils/validation.ts

@@ -1,62 +0,0 @@
-import type { SurveyPageData, SurveyQuestion } from '../../fetchSurvey/types';
-
-/**
- * Validates a list of questions against user values and returns an error map.
- *
- * @param questions List of questions to validate.
- * @param values User selected values mapped by question ID.
- * @param language Active survey language code.
- * @returns Object mapping question ID to localized validation error messages.
- */
-export function validateQuestions(
-  questions: SurveyQuestion[],
-  values: Record<string, string | number>,
-  language?: string
-): Record<string, string> {
-  const errors: Record<string, string> = {};
-  questions.forEach(question => {
-    if (question.required && (values[question.id] === undefined || values[question.id] === '')) {
-      errors[question.id] =
-        question.requiredErrorMessage ??
-        (language?.startsWith('de')
-          ? 'Beantworten Sie bitte diese Frage bevor Sie fortfahren.'
-          : 'Please answer this question before you proceed.');
-    }
-  });
-  return errors;
-}
-
-/**
- * Validates all survey pages and returns details of the first validation error found.
- *
- * @param pages List of pages to validate.
- * @param values User selected values mapped by question ID.
- * @param language Active survey language code.
- * @returns Validation error details containing all errors, target error page index, and target error element ID, or null if all checks pass.
- */
-export function validateAllPages(
-  pages: SurveyPageData[],
-  values: Record<string, string | number>,
-  language?: string
-): { errors: Record<string, string>; errorPageIndex: number; firstErrorId: string } | null {
-  let errors: Record<string, string> = {};
-  let firstErrorId = '';
-  let errorPageIndex = -1;
-
-  for (let i = 0; i < pages.length; i++) {
-    const pageErrors = validateQuestions(pages[i].questions, values, language);
-    if (Object.keys(pageErrors).length > 0) {
-      errors = { ...errors, ...pageErrors };
-      if (errorPageIndex === -1) {
-        errorPageIndex = i;
-        firstErrorId = Object.keys(pageErrors)[0];
-      }
-    }
-  }
-
-  if (errorPageIndex !== -1) {
-    return { errors, errorPageIndex, firstErrorId };
-  }
-
-  return null;
-}