Missing Sock

Missing Sock is a developer-friendly library for building interactive quizzes and assessments in React applications. It provides a flexible and customizable framework to create, manage, and evaluate assessments with ease.

Table of Contents

• Installation
• Getting Started
• Usage
  • Props and Events
  • Example Question Schema
• Example
• API Reference
• Contributing
• License

Installation

Install Missing Sock and its dependencies via npm or yarn:

npm install missing-sock
# or
yarn add missing-sock

Note: Ensure that your project has React and TypeScript configured, as Missing Sock is built with TypeScript support.

Getting Started

Import the Assessment component into your React application and define your assessment schema. Handle events such as start, completion, scoring, and metrics to integrate the assessment flow seamlessly.

Usage

Props and Events

The Assessment component accepts the following props:

• questions (Schema): The assessment schema defining sections and questions.
• onStart (() => void): Optional. Callback triggered when the assessment starts.
• onComplete ((responses: Record<string, Response>) => void): Required. Callback triggered upon assessment completion with all user responses.
• onScore ((responses: Record<string, Response>) => number): Optional. Callback to calculate the assessment score based on responses.
• onMetrics ((metrics: { totalTime: number; timePerQuestion: Record<string, number> }) => void): Optional. Callback to capture metrics such as total time taken and time per question.

Example Question Schema

Below is an example of a Schema with a binary question:

import { Schema } from 'missing-sock'

const exampleSchema: Schema = {
  sections: [
    {
      title: 'General Knowledge',
      questions: [
        {
          id: 'q1',
          type: 'binary',
          prompt: 'Is the sky blue?',
          options: [
            { label: 'Yes', value: 'yes' },
            { label: 'No', value: 'no' },
          ],
        },
        // Add more questions here
      ],
    },
    // Add more sections here
  ],
}

Example

Here’s a complete example demonstrating how to use Missing Sock to create a simple assessment with a binary question:

import React from 'react'
import { Assessment, Schema, Response } from 'missing-sock'

const exampleSchema: Schema = {
  sections: [
    {
      title: 'General Knowledge',
      questions: [
        {
          id: 'q1',
          type: 'binary',
          prompt: 'Is the sky blue?',
          options: [
            { label: 'Yes', value: 'yes' },
            { label: 'No', value: 'no' },
          ],
        },
        // Add more questions as needed
      ],
    },
  ],
}

function App() {
  const handleStart = () => {
    console.log('Assessment started')
  }

  const handleComplete = (responses: Record<string, Response>) => {
    console.log('Assessment completed with responses:', responses)
  }

  const handleScore = (responses: Record<string, Response>): number => {
    let score = 0
    if (responses.q1 === 'yes') score += 1
    // Calculate score based on responses
    return score
  }

  const handleMetrics = (metrics: { totalTime: number; timePerQuestion: Record<string, number> }) => {
    console.log('Assessment metrics:', metrics)
  }

  return (
    <div>
      <h1>Quiz Time!</h1>
      <Assessment
        questions={exampleSchema}
        onStart={handleStart}
        onComplete={handleComplete}
        onScore={handleScore}
        onMetrics={handleMetrics}
      />
    </div>
  )
}

export default App

Explanation

1. Define the Schema: Create a Schema object that outlines the sections and questions of your assessment. In the example, there's one section titled "General Knowledge" containing a binary question.

2. Handle Events:

   • onStart: Logs a message when the assessment begins.
   • onComplete: Receives all user responses upon completion and logs them.
   • onScore: Calculates a simple score based on the user's response.
   • onMetrics: Logs metrics such as total time taken and time per question.

3. Render the Assessment: Include the Assessment component in your JSX, passing the schema and event handlers as props.

API Reference

Assessment Component

Props

| Name | Type | Description | | ------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | questions | Schema | Required. The assessment schema defining the sections and questions. | | onStart | () => void | Optional. Callback invoked when the assessment starts. | | onComplete | (responses: Record<string, Response>) => void | Required. Callback invoked upon assessment completion with all user responses. | | onScore | (responses: Record<string, Response>) => number | Optional. Callback to calculate the score based on user responses. | | onMetrics | (metrics: { totalTime: number; timePerQuestion: Record<string, number> }) => void | Optional. Callback to capture assessment metrics such as total time and time per question. |

Schema Type

Defines the structure of the assessment.

interface Schema {
  sections: Section[];
}

interface Section {
  title: string;
  questions: Question[];
}

type Question = BinaryQuestion | /* other question types */;

interface BinaryQuestion {
  id: string;
  type: "binary";
  prompt: string;
  options: { label: string; value: string }[];
}

Response Type

Represents a user's response to a question.

type Response = string // Modify based on question types

License

MIT