# 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](#installation)
- [Getting Started](#getting-started)
- [Usage](#usage)
  - [Props and Events](#props-and-events)
  - [Example Question Schema](#example-question-schema)
- [Example](#example)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Installation

Install **Missing Sock** and its dependencies via npm or yarn:

```bash
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:

```typescript
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:

```tsx
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.

```typescript
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.

```typescript
type Response = string // Modify based on question types
```

## License

[MIT](LICENSE)

---