@constructor-io/constructorio-ui-quizzes 1.7.1 → 1.8.0

package/lib/mjs/utils.js

@@ -41,6 +41,7 @@ export const functionStrings = {
     onQuizResultClick: `(result, position) => console.dir(result, position)`,
     onAddToFavoritesClick: `(item) => console.dir(item)`,
     onQuizResultsLoaded: `(results) => console.dir(results)`,
+    onQuizNextQuestion: `(question) => console.dir(question)`,
     cioJsClient: `cioJsClient`,
 };
 export const stringifyWithDefaults = (obj) => {
@@ -105,10 +106,12 @@ export const resetQuizSessionStorageState = (quizStateKey) => () => {
     window?.sessionStorage?.removeItem(quizStateKey);
 };
 export const logger = (action) => {
-    console.group(`%cAction:%c  ${action.type}`, 'color: red; font-weight: bold;', 'color: green; font-weight: lighter;');
-    console.log('%c type:', 'color: #9E9E9E; font-weight: 700;', action.type);
-    console.log('%c payload:', 'color: #00A7F7; font-weight: 700;', action.payload);
-    console.groupEnd();
+    if (process?.env?.LOGGER) {
+        console.group(`%cAction:%c  ${action.type}`, 'color: red; font-weight: bold;', 'color: green; font-weight: lighter;');
+        console.log('%c type:', 'color: #9E9E9E; font-weight: 700;', action.type);
+        console.log('%c payload:', 'color: #00A7F7; font-weight: 700;', action.payload);
+        console.groupEnd();
+    }
 };
 // Function to emulate pausing between interactions
 export function sleep(ms) {

package/lib/types/constants.d.ts

@@ -1,12 +1,13 @@
 export declare const apiKey = "key_wJSdZSiesX5hiVLt";
 export declare const quizId = "coffee-quiz";
 export declare const quizSessionStateKey = "constructorIOQuizState";
-export declare const componentDescription = "- import `CioQuiz` to render in your JSX.\n- This component handles state management, data fetching, and rendering logic.\n- To use this component, `quizId`, `resultsPageOptions`, and one of `apiKey` or `cioJsClient` are required.\n- `resultsPageOptions` lets you configure the results page\n  - `onAddToCartClick` is a callback function that will be called when the \"Add to cart\" button is clicked\n  - `onAddToFavoritesClick` is an optional callback function that will be called when the \"Add To Favorites\" heart icon is clicked\n  - `onQuizResultClick` is an optional callback function that will be called when the result card is clicked. The default behavior is redirecting the user to the item's URL\n  - `onQuizResultsLoaded` is an optional callback function that will be called when the quiz results are loaded\n  - `resultCardRegularPriceKey` is a parameter that specifies the metadata field name for the regular price\n  - `resultCardSalePriceKey` is an optional parameter that specifies the metadata field name for the sale price \n  - `resultCardRatingCountKey` is an optional parameter that specifies the metadata field name for the ratings count \n  - `resultCardRatingScoreKey` is an optional parameter that specifies the metadata field name for the ratings score \n  - `renderResultCardPriceDetails` is an optional render function to render custom prices section in result card \n  - `numResultsToDisplay` is an optional parameter that determines how many results should be displayed on results page\n- `sessionStateOptions` lets you configure the session modal behavior\n  - `showSessionModal` is a boolean used to decide whether to show the session modal. The default behavior is to show the session modal\n  - `showSessionModalOnResults` is a boolean to decide whether to show the session modal after reaching the results page. The default behavior is to not show the session modal\n  - `sessionStateKey` is a custom string that will be used as a session storage key\n- Use different props to configure the behavior of this component.\n- The following stories show how different props affect the component's behavior\n\n> Note: `cioJsClient` refers to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n";
+export declare const componentDescription = "- import `CioQuiz` to render in your JSX.\n- This component handles state management, data fetching, and rendering logic.\n- To use this component, `quizId`, `resultsPageOptions`, and one of `apiKey` or `cioJsClient` are required.\n- `resultsPageOptions` lets you configure the results page\n  - `onAddToCartClick` is a callback function that will be called when the \"Add to cart\" button is clicked\n  - `onAddToFavoritesClick` is an optional callback function that will be called when the \"Add To Favorites\" heart icon is clicked\n  - `onQuizResultClick` is an optional callback function that will be called when the result card is clicked. The default behavior is redirecting the user to the item's URL\n  - `onQuizResultsLoaded` is an optional callback function that will be called when the quiz results are loaded\n  - `resultCardRegularPriceKey` is a parameter that specifies the metadata field name for the regular price\n  - `resultCardSalePriceKey` is an optional parameter that specifies the metadata field name for the sale price \n  - `resultCardRatingCountKey` is an optional parameter that specifies the metadata field name for the ratings count \n  - `resultCardRatingScoreKey` is an optional parameter that specifies the metadata field name for the ratings score \n  - `renderResultCardPriceDetails` is an optional render function to render custom prices section in result card \n  - `numResultsToDisplay` is an optional parameter that determines how many results should be displayed on results page\n- `callbacks` lets you pass callback functions that will be called on certain actions\n  - `onQuizNextQuestion` is an optional callback function that will be called when user moves to the next question\n- `sessionStateOptions` lets you configure the session modal behavior\n  - `showSessionModal` is a boolean used to decide whether to show the session modal. The default behavior is to show the session modal\n  - `showSessionModalOnResults` is a boolean to decide whether to show the session modal after reaching the results page. The default behavior is to not show the session modal\n  - `sessionStateKey` is a custom string that will be used as a session storage key\n- Use different props to configure the behavior of this component.\n- The following stories show how different props affect the component's behavior\n\n> Note: `cioJsClient` refers to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n";
 export declare const hookDescription = "- import `useCioQuiz` and call this custom hook in a functional component.\n- This hook leaves rendering logic up to you, while handling:\n  - state management\n  - data fetching\n  - keyboard navigation\n  - mouse interactions\n  - focus and submit event handling\n- Since the markup is controlled by you, the default styles might not be applied if you have a different DOM structure\n- To use this hook, an `apiKey` and `quizId` are required, and `resultsPageOptions` must be passed to the `useCioQuiz` hook to configure behavior. All other values are optional.\n- use the <a href=\"https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters\" target=\"__blank\">prop getters</a> and other variables returned by this hook (below) to leverage the functionality described above with jsx elements in your react component definitions\n\nCalling the `useCioQuiz` hook returns an object with the following keys:\n\n```jsx\nconst {\n  // must be used for a hooks integrations\n  state: QuizReturnState, // Quiz state\n  events: [{...}], // array of quiz events\n  getAddToCartButtonProps: () => ({...})), // prop getter for jsx add to cart button for quiz result,\n  getAddToFavoritesButtonProps: () => ({...})), // prop getter for jsx add to favorites button for quiz result,\n  getCoverQuestionProps: () => ({...})), // prop getter for jsx quiz cover question,\n  getHydrateQuizButtonProps: () => ({...})), // prop getter for jsx hydrate quiz button,\n  getNextQuestionButtonProps: () => ({...})), // prop getter for jsx next button to traverse the quiz,\n  getPreviousQuestionButtonProps: () => ({...})), // prop getter for jsx back button to traverse the quiz, \n  getOpenTextInputProps: () => ({...})), // prop getter for jsx open text input,\n  getSelectInputProps: () => ({...})), // prop getter for jsx select input for select type questions,\n  getQuizImageProps: () => ({...})), // prop getter for jsx quiz image,\n  getQuizResultButtonProps: () => ({...})), // prop getter for jsx result card click as a button,\n  getQuizResultLinkProps: () => ({...})), // prop getter for jsx result card click as a link. Should be spread into <a> tags,\n  getResetQuizButtonProps: () => ({...})), // prop getter for jsx reset quiz button,\n  cioClient, // instance of constructorio-client-javascript\n } = useCioQuiz(args);\n```\n\n> Note: when we say `cioClient`, we are referring to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n";
 export declare const basicDescription = "Pass an `apiKey` and a `quizId` to request questions and quiz results from Constructor's servers";
 export declare const cioJsClientDescription = "If you are already using an instance of the `ConstructorIOClient`, you can pass a `cioJsClient` instead of an `apiKey` to request results from Constructor's servers\n\n> Note: `cioJsClient` refers to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)";
 export declare const smallContainerDescription = "If you are using the provided styles, CioQuiz component will respect the height and width of its parent container and use responsive styles based on the parent container's dimensions";
 export declare const changePrimaryColorDescription = "\nIf you would like to use a different primary color, pass a `primaryColor` string in RGB format ('R, G, B').\n\nAccent colors for borders and different states (hover, focus, active) will be calculated automatically based on the primary color you provided.\n\nBy default, the primary color has a value of \"35, 71, 199\" (Constructor Blue).\n\nIn the example below, the `primaryColor` prop has been used to override this color to \"255, 82, 48\" (Orange).\n\n> Advanced Option: Instead of passing a primaryColor prop, you can also override `--primary-color-h`, `--primary-color-s`, and `--primary-color-l` CSS variables within a `.cio-quiz` container element. If explicitly given a value in your CSS, then the values of these variables will be used as the HSL values for your quiz.\n";
+export declare const callbacksDescription = "Pass an `apiKey`, a `quizId`, and `callbacks`";
 export declare enum RequestStates {
     Stale = "STALE",
     Loading = "LOADING",

package/lib/types/hooks/useQuizEvents/useHydrateQuizLocalState.d.ts

@@ -1,4 +1,4 @@
 import { ActionAnswerQuestion } from '../../components/CioQuiz/actions';
 import { QuizEventsReturn } from '../../types';
-declare const useHydrateQuizLocalState: (quizStateKey: string, dispatchLocalState: React.Dispatch<ActionAnswerQuestion>) => QuizEventsReturn.NextQuestion;
+declare const useHydrateQuizLocalState: (quizSessionStorageStateKey: string, dispatchLocalState: React.Dispatch<ActionAnswerQuestion>) => QuizEventsReturn.NextQuestion;
 export default useHydrateQuizLocalState;

package/lib/types/hooks/useQuizEvents/useQuizNextClick.d.ts

@@ -1,6 +1,6 @@
 import { ActionAnswerQuestion } from '../../components/CioQuiz/actions';
 import { QuizAPIReducerState } from '../../components/CioQuiz/quizApiReducer';
 import { QuizLocalReducerState } from '../../components/CioQuiz/quizLocalReducer';
-import { QuizEventsReturn } from '../../types';
-declare const useQuizNextClick: (quizApiState: QuizAPIReducerState, quizLocalState: QuizLocalReducerState, dispatchLocalState: React.Dispatch<ActionAnswerQuestion>) => QuizEventsReturn.NextQuestion;
+import { QuizEventsReturn, OnQuizNextQuestion } from '../../types';
+declare const useQuizNextClick: (quizApiState: QuizAPIReducerState, quizLocalState: QuizLocalReducerState, dispatchLocalState: React.Dispatch<ActionAnswerQuestion>, onQuizNextQuestion?: OnQuizNextQuestion) => QuizEventsReturn.NextQuestion;
 export default useQuizNextClick;

package/lib/types/hooks/useQuizState/index.d.ts

@@ -3,15 +3,13 @@ import ConstructorIOClient from '@constructor-io/constructorio-client-javascript
 import { ActionAnswerQuestion, ActionQuizAPI } from '../../components/CioQuiz/actions';
 import { QuizAPIReducerState } from '../../components/CioQuiz/quizApiReducer';
 import { QuizLocalReducerState } from '../../components/CioQuiz/quizLocalReducer';
-import { IQuizProps } from '../../types';
+import { IQuizProps, QuizSessionStorageState } from '../../types';
 type UseQuizState = (quizOptions: IQuizProps, cioClient: ConstructorIOClient) => {
     quizApiState: QuizAPIReducerState;
     quizLocalState: QuizLocalReducerState;
     dispatchApiState: React.Dispatch<ActionQuizAPI>;
     dispatchLocalState: React.Dispatch<ActionAnswerQuestion>;
-    hasQuizStoredState: () => boolean;
-    skipToResults: boolean;
-    quizStateKey: string;
+    quizSessionStorageState: QuizSessionStorageState;
 };
 declare const useQuizState: UseQuizState;
 export default useQuizState;

package/lib/types/hooks/useQuizState/useQuizLocalState.d.ts

@@ -1,10 +1,6 @@
 import { ActionAnswerQuestion } from '../../components/CioQuiz/actions';
-import { SessionStateOptions } from '../../types';
-declare const useQuizLocalState: (sessionStateOptions?: SessionStateOptions) => {
+declare const useQuizLocalState: () => {
     quizLocalState: import("../../components/CioQuiz/quizLocalReducer").QuizLocalReducerState;
-    hasQuizStoredState: () => boolean;
     dispatchLocalState: (action: ActionAnswerQuestion) => void;
-    skipToResults: boolean;
-    quizStateKey: string;
 };
 export default useQuizLocalState;

package/lib/types/hooks/useQuizState/useSessionStorageState.d.ts

@@ -0,0 +1,8 @@
+import { SessionStateOptions } from '../../types';
+import { QuizLocalReducerState } from '../../components/CioQuiz/quizLocalReducer';
+declare const useSessionStorageState: (quizLocalState?: QuizLocalReducerState, sessionStateOptions?: SessionStateOptions, enableHydration?: boolean) => {
+    skipToResults: boolean;
+    quizSessionStorageStateKey: string;
+    hasSessionStorageState: () => boolean;
+};
+export default useSessionStorageState;

package/lib/types/types.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="react" />
-import { QuizResultData, NextQuestionResponse, QuizResultsResponse, Nullable, QuestionOption } from '@constructor-io/constructorio-client-javascript/lib/types';
+import { QuizResultData, NextQuestionResponse, QuizResultsResponse, Nullable, QuestionOption, Question } from '@constructor-io/constructorio-client-javascript/lib/types';
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import { RequestStates } from './constants';
 import { QuestionTypes } from './components/CioQuiz/actions';
@@ -30,6 +30,13 @@ export interface SessionStateOptions {
     showSessionModalOnResults?: boolean;
     sessionStateKey?: string;
 }
+export type QuestionWithAnswer = Question & {
+    answer: AnswerInput;
+};
+export type OnQuizNextQuestion = (question: QuestionWithAnswer) => void;
+export interface Callbacks {
+    onQuizNextQuestion?: OnQuizNextQuestion;
+}
 export interface IQuizProps {
     apiKey?: string;
     cioJsClient?: ConstructorIOClient;
@@ -38,6 +45,8 @@ export interface IQuizProps {
     resultsPageOptions: ResultsPageOptions;
     sessionStateOptions?: SessionStateOptions;
     primaryColor?: string;
+    enableHydration?: boolean;
+    callbacks?: Callbacks;
 }
 export interface QuizReturnState {
     answers: {
@@ -50,16 +59,22 @@ export interface QuizReturnState {
         sessionId?: string;
         currentQuestion?: CurrentQuestion | undefined;
         results?: QuizResultsResponse | undefined;
-        skipToResults: boolean;
         selectedOptionsWithAttributes?: string[];
     };
+    quizSessionStorageState: QuizSessionStorageState;
 }
+export type AnswerInput = {
+    type: InputQuestionsTypes;
+    value: string | string[];
+};
 export type AnswerInputState = {
-    [key: string]: {
-        type: InputQuestionsTypes;
-        value: string | string[];
-    };
+    [key: string]: AnswerInput;
 };
+export interface QuizSessionStorageState {
+    key: string;
+    skipToResults: boolean;
+    hasSessionStorageState: () => boolean;
+}
 export type InputQuestionsTypes = QuestionTypes.OpenText | QuestionTypes.Cover | QuestionTypes.SingleSelect | QuestionTypes.MultipleSelect;
 export type CurrentQuestion = NextQuestionResponse & {
     isFirstQuestion: boolean;
@@ -78,7 +93,6 @@ export declare namespace QuizEventsReturn {
     type AddToCart = (e: React.MouseEvent<HTMLElement>, result: QuizResultDataPartial, price?: number) => void;
     type AddToFavorites = (e: React.MouseEvent<HTMLElement>, result: QuizResultDataPartial, price?: number, sendEvent?: boolean) => void;
     type HydrateQuiz = () => void;
-    type HasSessionStorageState = () => boolean;
     type ResetSessionStorageState = () => void;
 }
 export interface QuizEventsReturn {
@@ -90,7 +104,6 @@ export interface QuizEventsReturn {
     addToCart: QuizEventsReturn.AddToCart;
     addToFavorites: QuizEventsReturn.AddToFavorites;
     hydrateQuiz: QuizEventsReturn.HydrateQuiz;
-    hasSessionStorageState: QuizEventsReturn.HasSessionStorageState;
     resetSessionStorageState: QuizEventsReturn.ResetSessionStorageState;
 }
 export interface OpenTextInputProps {

package/lib/types/utils.d.ts

@@ -17,6 +17,7 @@ export declare const functionStrings: {
     onQuizResultClick: string;
     onAddToFavoritesClick: string;
     onQuizResultsLoaded: string;
+    onQuizNextQuestion: string;
     cioJsClient: string;
 };
 export declare const stringifyWithDefaults: (obj: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-quizzes",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Constructor.io Quizzes UI library for web applications",
   "author": "constructor.io",
   "license": "MIT",