commons-assessment 12.0.30 → 12.0.32

package/README.md

@@ -1,203 +1,211 @@
-# Commons Assessment Library
-
-This library provides a comprehensive set of tools and components to create and manage assessments (Maker module), as well as to facilitate users in taking assessments (Taker module) within an Angular application.
-
-## Version Compatibility
-
-- **Version 12**: For Angular 12+ usage.
-
-## Dependencies
-
-The library uses Bootstrap styles and requires the following modules to be imported in your application:
-- `BrowserAnimationsModule`
-- `HttpClientModule`
-- `CommonsAssessmentModule`
-- `AssessmentMakerModule` (If creating assessments)
-- `AssessmentTakerModule` (If rendering assessments)
-
-## Installation & Configuration
-
-### 1. Import Modules
-
-Import the appropriate modules in your `app.module.ts`. You must configure `CommonsAssessmentModule` with `forRoot()` to provide the backend base URL.
-
-```typescript
-import { CommonsAssessmentModule, AssessmentMakerModule, AssessmentTakerModule } from 'commons-assessment';
-
-@NgModule({
-  imports: [
-    CommonsAssessmentModule.forRoot({
-      baseURL: 'https://dev.platformcommons.org', // Use your backend API base URL
-    }),
-    AssessmentMakerModule,
-    AssessmentTakerModule
-  ]
-})
-```
-
-### 2. Configure `angular.json`
-
-Add the necessary assets and global styles in your `angular.json` file inside the `architect.build.options` block.
-
-**Assets:**
-Add the library assets and angular-editor icons to the `assets` array.
-```json
-"assets": [
-  {
-    "glob": "**/*",
-    "input": "node_modules/commons-assessment/src/lib/assets",
-    "output": "assets/commons-assessment"
-  },
-  {
-    "glob": "**/*",
-    "input": "node_modules/@kolkov/angular-editor/assets/icons",
-    "output": "assets/ae-icons/"
-  }
-]
-```
-
-**Styles:**
-Include the library's global styles and third-party dependencies in the `styles` array.
-```json
-"styles": [
-  "src/styles.scss",
-  "node_modules/commons-assessment/src/lib/assets/theme/styles.global.scss",
-  "node_modules/@kolkov/angular-editor/themes/default.scss"
-]
-```
-
-### 3. Theming Setup (`styles.scss`)
-
-The library provides a mixin to easily customize the theme, including fonts and color variables. Set this up in your application's global `styles.scss`:
-
-```scss
-// Import the library's theme mixin
-@use "/node_modules/commons-assessment/src/lib/assets/theme/theme.global" as theme;
-// Import Bootstrap and Material core styles
-@import "~bootstrap/dist/css/bootstrap.min.css";
-@import "@angular/material/prebuilt-themes/indigo-pink.css";
-
-// Include customized variables into the theme
-:root {
-    @include theme.assessment-theme(
-        (
-            font-family: "Poppins",
-            // You can override library palette by uncommenting and modifying below:
-            // primary-one: #2e7d32,
-            // primary-four: #1b5e20,
-            // palette-EDF3FD: #e8f5e9,
-            // grey-one: #fff,
-        )
-    );
-}
-```
-
-## Component Usage
-
-### Assessment Maker
-
-To render the assessment maker interface, use the `<lib-assessment-maker>` component in your template.
-
-**`component.ts`**:
-```typescript
-
-export class Component {
-  // Define default structure or data payload for the assessment
-  createAssessmentDTO: Assessment = {
-    assessmentCode: 'TEST_ASSESSMENT_CODE',
-    domain: 'domain.test',
-    assessmentName: [{
-      id: 0,
-      text: 'test assessment',
-      language: {
-        code: 'ENG',
-      }
-    }],
-    tenant: 123
-  };
-}
-```
-
-**`component.html`**:
-```html
-  <lib-assessment-maker 
-    [defaultAssessmentDTO]="createAssessmentDTO"
-    [assessmentId]="2298"
-    [showFooter]="true">
-  </lib-assessment-maker>
-```
-
-#### Maker Inputs and Outputs
-
-| Property | Type (`@Input` / `@Output`) | Data Type | Description |
-| --- | --- | --- | --- |
-| `[labelConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration strings to overwrite internal labels. |
-| `[imageConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration paths/URLs to overwrite internal icons or images. |
-| `[questionTypes]` | `@Input` | `QuestionType[]` | (Optional) Restrict or customize the array of available question types. |
-| `[showFooter]` | `@Input` | `boolean` | (Optional) Toggles visibility of the assessment component footer actions. |
-| `[customRules]` | `@Input` | `any` | (Optional) Pass your custom question builder rules overrides. |
-| `[assessmentId]` | `@Input` | `number` | Provide the ID of an existing assessment to edit or attach questions to. Default is 0. |
-| `[assessmentInstanceId]` | `@Input` | `number` | Current assessment instance identifier, if the assessment is already published. Default is 0. |
-| `[defaultAssessmentDTO]` | `@Input` | `Assessment` | The default contextual configuration object for creating new assessments. |
-| `[predefinedAssessmentInstance]` | `@Input` | `AssessmentInstance` | The default contextual configuration object for creating new assessment instances. |
-| `[minimumRequiredSections]` | `@Input` | `number` | Minimum number of sections needed before assessment can be published. Default is 0. |
-| `[assessmentContext]` | `@Input` | `AssessmentContext` | (Optional) Pre-loaded assessment context data to bypass the initial data load API call. |
-| `(assessmentIdChange)` | `@Output` | `EventEmitter<number>` | Emits the new `assessmentId` when an assessment is successfully created. |
-| `(assessmentInstanceIdChange)` | `@Output` | `EventEmitter<number>` | Emits the new instance ID integer when an assessment is published. |
-| `(snackbarMessage)` | `@Output` | `EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }>` | Emits message status updates representing errors and workflow successes from the service. |
-
-### Assessment Taker
-
-To render the assessment taker interface, use the `<lib-assessment-taker>` component in your template.
-
-**`component.html`**:
-```html
-  <lib-assessment-taker
-    [labelConfig]="{}"
-    [imageConfig]="{}"
-    [assessmentId]="2298"
-    [assessmentInstanceId]="1135"
-    [assesseeData]="assesseeData"
-    [assessorData]="assessorData"
-    [showFooter]="true"
-    [disabled]="false"
-    [previewMode]="false"
-    [verticalView]="false"
-    [enableMarks]="false"
-    [assessmentContext]="assessmentContext"
-    (submitAssessment)="onSubmit($event)"
-    (snackbarMessage)="onSnackbarMessage($event)">
-  </lib-assessment-taker>
-```
-
-#### Taker Inputs and Outputs
-
-| Property | Type (`@Input` / `@Output`) | Data Type | Description |
-| --- | --- | --- | --- |
-| `[labelConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration strings to overwrite internal labels. |
-| `[imageConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration paths/URLs to overwrite internal icons or images. |
-| `[assessmentId]` | `@Input` | `number` | **Required.** Provide the ID of an existing assessment to take. |
-| `[assessmentInstanceId]` | `@Input` | `number` | **Required.** The published instance ID of the assessment. |
-| `[assesseeData]` | `@Input` | `AssesseeDTO` | **Required.** Data concerning the person taking the assessment. |
-| `[assessorData]` | `@Input` | `AssessorDTO` | **Required.** Data concerning the entity or person grading/creating the assessment. |
-| `[showFooter]` | `@Input` | `boolean` | (Optional) Toggles visibility of the assessment component footer actions. |
-| `[disabled]` | `@Input` | `boolean` | (Optional) Disables the form to prevent interaction. |
-| `[previewMode]` | `@Input` | `boolean` | (Optional) Disables interaction and enables preview functionality. |
-| `[verticalView]` | `@Input` | `boolean` | (Optional) Displays the assessment sections vertically instead of tabs. |
-| `[enableMarks]` | `@Input` | `boolean` | (Optional) Enables ability to view or provide marks. |
-| `[assessmentContext]` | `@Input` | `AssessmentContextDTO` | (Optional) Pre-loaded assessment context data to bypass the initial data load API call. |
-| `[assesseeResponse]` | `@Input` | `AssessmentInstanceAssesseDTO` | (Optional) Pre-loaded assessee response data to bypass the initial data load API call. |
-| `[hideSectionTabs]` | `@Input` | `boolean` | (Optional) Hides the section tabs. |
-| `[markAsCompleted]` | `@Input` | `boolean` | (Optional) Marks the assessment as completed when the last section is submitted. Default is true. |
-| `[sectionWiseScore]` | `@Input` | `{ [sectionId: number]: SectionScore }` | (Optional) Shows section wise score. Default is null. |
-| `[showOverallRemarks]` | `@Input` | `boolean` | (Optional) Shows overall remarks field. Default is false. |
-| `[showCorrectAnswers]` | `@Input` | `boolean` | (Optional) Shows correct and incorrect answers for objective and multiselect type questions. Default is false. |
-| `[enableSkillsToQuestionMapping]` | `@Input` | `boolean` | (Optional) Enables ability to map skills to questions. Default is false. |
-| `(stepChanged)` | `@Output` | `EventEmitter<{ currentStepIndex: number, totalSteps: number, isLastStep: boolean }>` | Emits initially and on every step change. Provides the current step index, total steps, and indicating boolean. |
-| `(submitAssessment)` | `@Output` | `EventEmitter<{ assesseeId: number, completed: boolean }>` | Emits when the assessment is submitted, containing the `assesseeId` and a `completed` flag indicating if the taker finished the entire assessment. |
-| `(snackbarMessage)` | `@Output` | `EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }>` | Emits message status updates representing errors and workflow successes from the service. |
-
-## Development Commands
-
-- Run `npm run build` or `ng build commons-assessment` to build the library project. The build artifacts will be stored in the `dist/` directory.
+# Commons Assessment Library
+
+This library provides a comprehensive set of tools and components to create and manage assessments (Maker module), as well as to facilitate users in taking assessments (Taker module) within an Angular application.
+
+## Version Compatibility
+
+- **Version 12**: For Angular 12+ usage.
+
+## Dependencies
+
+The library uses Bootstrap styles and requires the following modules to be imported in your application:
+- `BrowserAnimationsModule`
+- `HttpClientModule`
+- `CommonsAssessmentModule`
+- `AssessmentMakerModule` (If creating assessments)
+- `AssessmentTakerModule` (If rendering assessments)
+
+## Installation & Configuration
+
+### 1. Import Modules
+
+Import the appropriate modules in your `app.module.ts`. You must configure `CommonsAssessmentModule` with `forRoot()` to provide the backend base URL.
+
+```typescript
+import { CommonsAssessmentModule, AssessmentMakerModule, AssessmentTakerModule } from 'commons-assessment';
+
+@NgModule({
+  imports: [
+    CommonsAssessmentModule.forRoot({
+      baseURL: 'https://dev.platformcommons.org', // Use your backend API base URL
+    }),
+    AssessmentMakerModule,
+    AssessmentTakerModule
+  ]
+})
+```
+
+### 2. Configure `angular.json`
+
+Add the necessary assets and global styles in your `angular.json` file inside the `architect.build.options` block.
+
+**Assets:**
+Add the library assets and angular-editor icons to the `assets` array.
+```json
+"assets": [
+  {
+    "glob": "**/*",
+    "input": "node_modules/commons-assessment/src/lib/assets",
+    "output": "assets/commons-assessment"
+  },
+  {
+    "glob": "**/*",
+    "input": "node_modules/@kolkov/angular-editor/assets/icons",
+    "output": "assets/ae-icons/"
+  }
+]
+```
+
+**Styles:**
+Include the library's global styles and third-party dependencies in the `styles` array.
+```json
+"styles": [
+  "src/styles.scss",
+  "node_modules/@kolkov/angular-editor/themes/default.scss"
+]
+```
+
+### 3. Theming Setup (`styles.scss`)
+
+The library provides a mixin to easily customize the theme, including fonts and color variables. Set this up in your application's global `styles.scss`:
+
+```scss
+// Import the library's theme mixin
+@use "/node_modules/commons-assessment/src/lib/assets/theme/theme.global" as theme;
+@import "commons-assessment/src/lib/assets/theme/styles.global";
+// Import Bootstrap and Material core styles
+@import "~bootstrap/dist/css/bootstrap.min.css";
+@import "@angular/material/prebuilt-themes/indigo-pink.css";
+
+// Include customized variables into the theme
+:root {
+    @include theme.assessment-theme(
+        (
+            font-family: "Poppins",
+            // You can override library palette by uncommenting and modifying below:
+            // primary-one: #2e7d32,
+            // primary-four: #1b5e20,
+            // palette-EDF3FD: #e8f5e9,
+            // grey-one: #fff,
+        )
+    );
+}
+```
+
+## Component Usage
+
+### Assessment Maker
+
+To render the assessment maker interface, use the `<lib-assessment-maker>` component in your template.
+
+**`component.ts`**:
+```typescript
+
+export class Component {
+  // Define default structure or data payload for the assessment
+  createAssessmentDTO: Assessment = {
+    assessmentCode: 'TEST_ASSESSMENT_CODE',
+    domain: 'domain.test',
+    assessmentName: [{
+      id: 0,
+      text: 'test assessment',
+      language: {
+        code: 'ENG',
+      }
+    }],
+    tenant: 123
+  };
+}
+```
+
+**`component.html`**:
+```html
+  <lib-assessment-maker 
+    [defaultAssessmentDTO]="createAssessmentDTO"
+    [assessmentId]="2298"
+    [showFooter]="true">
+  </lib-assessment-maker>
+```
+
+#### Maker Inputs and Outputs
+
+| Property | Type (`@Input` / `@Output`) | Data Type | Description |
+| --- | --- | --- | --- |
+| `[labelConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration strings to overwrite internal labels. |
+| `[imageConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration paths/URLs to overwrite internal icons or images. |
+| `[questionTypes]` | `@Input` | `QuestionType[]` | (Optional) Restrict or customize the array of available question types. |
+| `[showFooter]` | `@Input` | `boolean` | (Optional) Toggles visibility of the assessment component footer actions. |
+| `[customRules]` | `@Input` | `any` | (Optional) Pass your custom question builder rules overrides. |
+| `[assessmentId]` | `@Input` | `number` | Provide the ID of an existing assessment to edit or attach questions to. Default is 0. |
+| `[assessmentInstanceId]` | `@Input` | `number` | Current assessment instance identifier, if the assessment is already published. Default is 0. |
+| `[defaultAssessmentDTO]` | `@Input` | `Assessment` | The default contextual configuration object for creating new assessments. |
+| `[predefinedAssessmentInstance]` | `@Input` | `AssessmentInstance` | The default contextual configuration object for creating new assessment instances. |
+| `[minimumRequiredSections]` | `@Input` | `number` | Minimum number of sections needed before assessment can be published. Default is 0. |
+| `[assessmentContext]` | `@Input` | `AssessmentContext` | (Optional) Pre-loaded assessment context data to bypass the initial data load API call. |
+| `(assessmentIdChange)` | `@Output` | `EventEmitter<number>` | Emits the new `assessmentId` when an assessment is successfully created. |
+| `(assessmentInstanceIdChange)` | `@Output` | `EventEmitter<number>` | Emits the new instance ID integer when an assessment is published. |
+| `(snackbarMessage)` | `@Output` | `EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }>` | Emits message status updates representing errors and workflow successes from the service. |
+
+### Assessment Taker
+
+To render the assessment taker interface, use the `<lib-assessment-taker>` component in your template.
+
+**`component.html`**:
+```html
+  <lib-assessment-taker
+    [labelConfig]="{}"
+    [imageConfig]="{}"
+    [assessmentId]="2298"
+    [assessmentInstanceId]="1135"
+    [assesseeData]="assesseeData"
+    [assessorData]="assessorData"
+    [showFooter]="true"
+    [disabled]="false"
+    [previewMode]="false"
+    [verticalView]="false"
+    [enableMarks]="false"
+    [assessmentContext]="assessmentContext"
+    (submitAssessment)="onSubmit($event)"
+    (snackbarMessage)="onSnackbarMessage($event)">
+  </lib-assessment-taker>
+```
+
+#### Taker Inputs and Outputs
+
+| Property | Type (`@Input` / `@Output`) | Data Type | Description |
+| --- | --- | --- | --- |
+| `[labelConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration strings to overwrite internal labels. |
+| `[imageConfig]` | `@Input` | `{ [key: string]: string }` | (Optional) Configuration paths/URLs to overwrite internal icons or images. |
+| `[assessmentId]` | `@Input` | `number` | **Required.** Provide the ID of an existing assessment to take. |
+| `[assessmentInstanceId]` | `@Input` | `number` | **Required.** The published instance ID of the assessment. |
+| `[assesseeData]` | `@Input` | `AssesseeDTO` | **Required.** Data concerning the person taking the assessment. |
+| `[assessorData]` | `@Input` | `AssessorDTO` | **Required.** Data concerning the entity or person grading/creating the assessment. |
+| `[showFooter]` | `@Input` | `boolean` | (Optional) Toggles visibility of the assessment component footer actions. |
+| `[disabled]` | `@Input` | `boolean` | (Optional) Disables the form to prevent interaction. |
+| `[previewMode]` | `@Input` | `boolean` | (Optional) Disables interaction and enables preview functionality. |
+| `[verticalView]` | `@Input` | `boolean` | (Optional) Displays the assessment sections vertically instead of tabs. |
+| `[enableMarks]` | `@Input` | `boolean` | (Optional) Enables ability to view or provide marks. |
+| `[assessmentContext]` | `@Input` | `AssessmentContextDTO` | (Optional) Pre-loaded assessment context data to bypass the initial data load API call. |
+| `[assesseeResponse]` | `@Input` | `AssessmentInstanceAssesseDTO` | (Optional) Pre-loaded assessee response data to bypass the initial data load API call. |
+| `[hideSectionTabs]` | `@Input` | `boolean` | (Optional) Hides the section tabs. |
+| `[markAsCompleted]` | `@Input` | `boolean` | (Optional) Marks the assessment as completed when the last section is submitted. Default is true. |
+| `[sectionWiseScore]` | `@Input` | `{ [sectionId: number]: SectionScore }` | (Optional) Shows section wise score. Default is null. |
+| `[showOverallRemarks]` | `@Input` | `boolean` | (Optional) Shows overall remarks field. Default is false. |
+| `[showCorrectAnswers]` | `@Input` | `boolean` | (Optional) Shows correct and incorrect answers for objective and multiselect type questions. Default is false. |
+| `[enableSkillsToQuestionMapping]` | `@Input` | `boolean` | (Optional) Enables ability to map skills to questions. Default is false. |
+| `(stepChanged)` | `@Output` | `EventEmitter<{ currentStepIndex: number, totalSteps: number, isLastStep: boolean }>` | Emits initially and on every step change. Provides the current step index, total steps, and indicating boolean. |
+| `(submitAssessment)` | `@Output` | `EventEmitter<{ assesseeId: number, completed: boolean }>` | Emits when the assessment is submitted, containing the `assesseeId` and a `completed` flag indicating if the taker finished the entire assessment. |
+| `(snackbarMessage)` | `@Output` | `EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }>` | Emits message status updates representing errors and workflow successes from the service. |
+
+## Detailed Documentation
+
+For a more comprehensive guide on features, detailed input/output variables, interfaces, custom events, and styling variables, please refer to the following documentation files:
+
+- **Assessment Maker Component**: [assessment-maker.md](../../documentation/assessment-maker.md)
+- **Assessment Taker Component**: [assessment-taker.md](../../documentation/assessment-taker.md)
+- **Theming & Styles Guide**: [theme.md](../../documentation/theme.md)
+
+## Development Commands
+
+- Run `npm run build` or `ng build commons-assessment` to build the library project. The build artifacts will be stored in the `dist/` directory.
 - Run `ng test commons-assessment` to execute the unit tests via [Karma](https://karma-runner.github.io).