Merge pull request #2370 from themeum/v4-quiz

✨ Build v4 learning-area quiz foundation

Author: shewa12

assets/core/scss/mixins/_inputs.scss

@@ -68,6 +68,7 @@
   background-color: $tutor-surface-l1;
   cursor: pointer;
   position: relative;
+  flex-shrink: 0;
   @include tutor-transition((
     background-color,
     border-color,
@@ -155,6 +156,7 @@
   background-color: $tutor-surface-l1;
   cursor: pointer;
   position: relative;
+  flex-shrink: 0;
   @include tutor-transition((
     background-color,
     border-color,

assets/core/scss/mixins/_layout.scss

@@ -118,12 +118,16 @@
   grid-template-columns: repeat($min, 1fr);
 
   @for $i from ($min + 1) through $max {
-    // Count all children, then subtract if any are dragging
+    // Count all children to increase column count; ignore drag clones.
     &:has(> #{$selector}:nth-child(#{$i})) {
       grid-template-columns: repeat($i, 1fr);
+    }
+  }
 
-      // If one child is dragging, reduce column count by 1
-      &:has(> #{$selector}[data-dnd-dragging='true']) {
+  // If a drag clone/placeholder is present, keep columns based on item count minus one.
+  &:has(> #{$selector}[data-dnd-dragging='true']) {
+    @for $i from ($min + 1) through ($max + 1) {
+      &:has(> #{$selector}:nth-child(#{$i})) {
         grid-template-columns: repeat(#{$i - 1}, 1fr);
       }
     }

assets/core/scss/themes/_dark.scss

@@ -64,6 +64,7 @@
   --tutor-icon-disabled: #{$tutor-gray-600};
   --tutor-icon-brand: #{$tutor-brand-600};
   --tutor-icon-brand-hover: #{$tutor-brand-700};
+  --tutor-icon-brand-secondary: #{$tutor-brand-300};
   --tutor-icon-exception1: #{$tutor-exception-1};
   --tutor-icon-exception2: #{$tutor-exception-2};
   --tutor-icon-success-primary: #{$tutor-success-600};

assets/core/scss/themes/_light.scss

@@ -65,6 +65,7 @@
   --tutor-icon-disabled: #{$tutor-gray-300};
   --tutor-icon-brand: #{$tutor-brand-600};
   --tutor-icon-brand-hover: #{$tutor-brand-700};
+  --tutor-icon-brand-secondary: #{$tutor-brand-300};
   --tutor-icon-exception1: #{$tutor-exception-1};
   --tutor-icon-exception2: #{$tutor-exception-2};
   --tutor-icon-success-primary: #{$tutor-success-700};

assets/core/scss/tokens/_icons.scss

@@ -12,6 +12,7 @@ $tutor-icon-secondary: var(--tutor-icon-secondary);
 $tutor-icon-subdued: var(--tutor-icon-subdued);
 $tutor-icon-brand: var(--tutor-icon-brand);
 $tutor-icon-brand-hover: var(--tutor-icon-brand-hover);
+$tutor-icon-brand-secondary: var(--tutor-icon-brand-secondary);
 $tutor-icon-success-primary: var(--tutor-icon-success-primary);
 $tutor-icon-critical: var(--tutor-icon-critical);
 $tutor-icon-critical-hover: var(--tutor-icon-critical-hover);
@@ -35,6 +36,7 @@ $tutor-icons: (
   subdued: $tutor-icon-subdued,
   brand: $tutor-icon-brand,
   brand-hover: $tutor-icon-brand-hover,
+  brand-secondary: $tutor-icon-brand-secondary,
   success-primary: $tutor-icon-success-primary,
   critical: $tutor-icon-critical,
   critical-hover: $tutor-icon-critical-hover,
@@ -44,4 +46,4 @@ $tutor-icons: (
   exception2: $tutor-icon-exception2,
   exception4: $tutor-icon-exception4,
   disabled: $tutor-icon-disabled,
-);
+);

assets/core/ts/components/form.ts

@@ -18,6 +18,7 @@ interface FieldConfig {
   defaultValue?: unknown;
   ref?: HTMLInputElement;
   type?: string;
+  isCheckboxArray?: boolean;
 }
 
 export interface ValidationRules {
@@ -418,42 +419,110 @@ export const form = (config: FormControlConfig & { id?: string } = {}) => {
       const isCheckbox = type === 'checkbox';
       const isFile = type === 'file';
 
-      const defaultValue = this.values[name] ?? (isCheckbox ? (element?.checked ?? false) : '');
+      // Check if a checkbox with this name is already registered (indicates multiple checkboxes)
+      const isCheckboxArray = isCheckbox && this.fields[name]?.type === 'checkbox';
+
+      let defaultValue: unknown;
+
+      if (isCheckboxArray) {
+        // Ensure array type for checkbox groups
+        const currentValue = this.values[name];
+        defaultValue = Array.isArray(currentValue) ? currentValue : [];
+      } else if (isCheckbox) {
+        defaultValue = this.values[name] ?? element?.checked ?? false;
+      } else {
+        defaultValue = this.values[name] ?? '';
+      }
 
       this.fields[name] = {
         name,
         rules,
         defaultValue,
         ref: element,
         type,
+        isCheckboxArray,
       };
 
-      this.values[name] ??= defaultValue;
+      // Force upgrade value to array if a collision is detected
+      if (isCheckboxArray && !Array.isArray(this.values[name])) {
+        this.values[name] = defaultValue;
+      } else {
+        this.values[name] ??= defaultValue;
+      }
 
-      const valueExpression = isCheckbox ? '$event.target.checked' : '$event.target.value';
+      const valueExpression = isCheckboxArray
+        ? '$event.target.value'
+        : isCheckbox
+          ? '$event.target.checked'
+          : '$event.target.value';
 
       const bindings: Record<string, unknown> = {
         name,
         'x-ref': name,
-        ':aria-invalid': `!!errors.${name}`,
+        ':aria-invalid': `!!errors["${name}"]`,
         ':class': `{
-          'tutor-input-error': errors.${name},
-          'tutor-input-touched': touchedFields.${name},
-          'tutor-input-dirty': dirtyFields.${name}
+          'tutor-input-error': errors["${name}"],
+          'tutor-input-touched': touchedFields["${name}"],
+          'tutor-input-dirty': dirtyFields["${name}"]
         }`,
       };
 
       if (!isFile) {
-        bindings['x-model'] = `values.${name}`;
-        bindings['@input'] = `handleFieldInput('${name}', ${valueExpression})`;
+        bindings['x-model'] = `values["${name}"]`;
+
+        bindings['@input'] = `handleFieldInput('${name}', ${valueExpression}, $event.target)`;
+
         bindings['@blur'] = `handleFieldBlur('${name}', ${valueExpression})`;
       }
 
       return bindings;
     },
 
-    handleFieldInput(name: string, value: unknown): void {
+    handleCheckboxArrayInput(name: string, element?: HTMLInputElement): void {
+      const field = this.fields[name];
+      const currentValue = this.values[name] as string[];
+      const valueArray = Array.isArray(currentValue) ? [...currentValue] : [];
+
+      // Use the passed element (from $event.target) or try to get from $refs
+      const checkbox = element || ((this as unknown as AlpineComponent).$refs[name] as HTMLInputElement);
+
+      if (!checkbox) return;
+
+      const checkboxValue = checkbox.value;
+      const isChecked = checkbox.checked;
+
+      let newValue: string[];
+      if (isChecked) {
+        newValue = valueArray.includes(checkboxValue) ? valueArray : [...valueArray, checkboxValue];
+      } else {
+        newValue = valueArray.filter((v) => v !== checkboxValue);
+      }
+
+      const defaultArray = Array.isArray(field.defaultValue) ? field.defaultValue : [];
+      // Sort to compare content regardless of order
+      const isActuallyChanged = JSON.stringify(newValue.sort()) !== JSON.stringify(defaultArray.sort());
+
+      this.values[name] = newValue;
+      this.dirtyFields[name] = isActuallyChanged;
+
+      const shouldValidate = this.config.mode === 'onChange' || this.touchedFields[name];
+
+      if (shouldValidate) {
+        this.validateField(name, newValue);
+      } else {
+        this.dispatchStateChange();
+      }
+    },
+
+    handleFieldInput(name: string, value: unknown, element?: HTMLInputElement): void {
       const field = this.fields[name];
+
+      if (field?.isCheckboxArray) {
+        this.handleCheckboxArrayInput(name, element);
+        return;
+      }
+
+      // Original logic for non-checkbox-array fields
       const isNumber = field?.rules?.numberOnly;
       const allowNegative = typeof isNumber === 'object' && isNumber.allowNegative;
       const whole = typeof isNumber === 'object' && isNumber.whole;
@@ -508,12 +577,22 @@ export const form = (config: FormControlConfig & { id?: string } = {}) => {
       if (shouldTouch) this.touchedFields[name] = true;
       if (shouldDirty) {
         const field = this.fields[name];
-        this.dirtyFields[name] = String(value) !== String(field?.defaultValue ?? '');
+        // Handle array comparison for checkbox arrays
+        if (Array.isArray(value) && Array.isArray(field?.defaultValue)) {
+          this.dirtyFields[name] = JSON.stringify(value.sort()) !== JSON.stringify(field.defaultValue.sort());
+        } else {
+          this.dirtyFields[name] = String(value) !== String(field?.defaultValue ?? '');
+        }
       }
 
       const fieldElement = this.fields[name]?.ref;
       if (fieldElement && this.fields[name].type !== 'file') {
-        DOMUtils.updateElementValue(fieldElement, value);
+        // For checkbox arrays, we need to update all checkboxes with this name
+        if (Array.isArray(value) && fieldElement.type === 'checkbox') {
+          this.syncCheckboxArray(name, value as string[]);
+        } else {
+          DOMUtils.updateElementValue(fieldElement, value);
+        }
       }
 
       if (shouldValidate) {
@@ -814,11 +893,29 @@ export const form = (config: FormControlConfig & { id?: string } = {}) => {
       for (const [name, value] of Object.entries(this.values)) {
         const fieldRef = this.fields[name]?.ref;
         if (fieldRef) {
-          DOMUtils.updateElementValue(fieldRef, value);
+          // Handle checkbox arrays specially
+          if (Array.isArray(value) && fieldRef.type === 'checkbox') {
+            this.syncCheckboxArray(name, value as string[]);
+          } else {
+            DOMUtils.updateElementValue(fieldRef, value);
+          }
         }
       }
     },
 
+    syncCheckboxArray(name: string, values: string[]): void {
+      const component = this as unknown as AlpineComponent;
+      const formElement = component.$el.closest('form') || component.$el.parentElement;
+      const checkboxes = formElement?.querySelectorAll(`input[type="checkbox"][name="${name}"]`);
+
+      if (checkboxes) {
+        checkboxes.forEach((checkbox) => {
+          const input = checkbox as HTMLInputElement;
+          input.checked = values.includes(input.value);
+        });
+      }
+    },
+
     clearAllState(): void {
       this.fields = {};
       this.values = {};

assets/core/ts/constant.ts

@@ -13,4 +13,6 @@ export const TUTOR_CUSTOM_EVENTS = {
   TUTOR_PLAYER_READY: 'tutor-player-ready',
   COMMENT_REPLIED: 'tutor:comment:replied',
   LESSON_PLAYER_READY: 'tutorLessonPlayerReady',
+  QUIZ_TIME_EXPIRED: 'tutor-quiz-time-expired',
+  QUIZ_ABANDON_REQUESTED: 'tutor-quiz-abandon-requested',
 };

assets/icons/clock-frame.svg

@@ -0,0 +1,83 @@
+import type { AlpineComponentMeta } from '@Core/ts/types';
+
+interface QuizSummarySidebarConfig {
+  firstQuestionId?: string | number;
+}
+
+const QUESTION_ID_PREFIX = 'question-';
+const SUMMARY_HEADER_SELECTOR = '.tutor-quiz-summary-header';
+const QUESTION_ID_FALLBACK_SELECTOR = '[data-question-id="%s"]';
+const QUESTION_ID_PREFIX_FALLBACK_SELECTOR = `[data-question-id="${QUESTION_ID_PREFIX}%s"]`;
+const SIDEBAR_ITEM_SELECTOR = '[data-question-id="%s"]';
+const HASH_PATTERN = new RegExp(`^#${QUESTION_ID_PREFIX}(\\d+)$`);
+const QUESTION_SCROLL_GAP = 16;
+
+const quizSummarySidebar = (config: QuizSummarySidebarConfig = {}) => ({
+  activeQuestionId: String(config.firstQuestionId ?? ''),
+  $el: null as HTMLElement | null,
+
+  init() {
+    const hashQuestionId = this.getQuestionIdFromHash(window.location.hash);
+
+    if (hashQuestionId && this.hasQuestionItem(hashQuestionId)) {
+      this.activeQuestionId = hashQuestionId;
+    }
+  },
+
+  getQuestionIdFromHash(hash: string): string | null {
+    const hashMatch = hash.match(HASH_PATTERN);
+    return hashMatch ? hashMatch[1] : null;
+  },
+
+  hasQuestionItem(questionId: string): boolean {
+    if (!questionId || !this.$el) {
+      return false;
+    }
+
+    return !!this.$el.querySelector(SIDEBAR_ITEM_SELECTOR.replace('%s', questionId));
+  },
+
+  setActiveQuestion(questionId: string | number) {
+    const resolvedId = String(questionId || '');
+
+    if (!resolvedId) {
+      return;
+    }
+
+    this.activeQuestionId = resolvedId;
+    history.replaceState(null, '', `#${QUESTION_ID_PREFIX}${resolvedId}`);
+    this.scrollToQuestionAnswer(resolvedId);
+  },
+
+  scrollToQuestionAnswer(questionId: string | number) {
+    const resolvedId = String(questionId || '');
+
+    if (!resolvedId) {
+      return;
+    }
+
+    const answerElement =
+      document.getElementById(`${QUESTION_ID_PREFIX}${resolvedId}`) ||
+      document.querySelector(QUESTION_ID_PREFIX_FALLBACK_SELECTOR.replace('%s', resolvedId)) ||
+      document.querySelector(QUESTION_ID_FALLBACK_SELECTOR.replace('%s', resolvedId));
+
+    if (answerElement instanceof HTMLElement) {
+      const summaryHeader = document.querySelector(SUMMARY_HEADER_SELECTOR);
+      const headerOffset =
+        summaryHeader instanceof HTMLElement
+          ? summaryHeader.getBoundingClientRect().top + summaryHeader.offsetHeight
+          : 0;
+      const scrollTop = answerElement.getBoundingClientRect().top + window.scrollY - headerOffset - QUESTION_SCROLL_GAP;
+
+      window.scrollTo({
+        top: Math.max(0, scrollTop),
+        behavior: 'smooth',
+      });
+    }
+  },
+});
+
+export const quizSummarySidebarMeta: AlpineComponentMeta = {
+  name: 'quizSummarySidebar',
+  component: quizSummarySidebar,
+};