Add the QTI associate interaction plugin by rtibblesbot · Pull Request #6113 · learningequality/studio

rtibblesbot · 2026-08-31T16:20:36Z

Summary

Associate questions could not be authored: an item whose body is <qti-associate-interaction> had no plugin, so it fell back to the choice descriptor and its header read "Unknown type". This adds the plugin end to end — the flat choice pool parses into correct pairs plus distractors, serializes back to a cardinality="multiple" base-type="pair" declaration, validates, and renders in an editor.

References

Fixes #6101.

Reviewer guidance

JS tests pass on CI. Beyond those, on the QTI demo page (/channels/<id>/#/qti-demo, question 7):

Edit the item, add a pair, and type into both cards — the header stays "Associate" and the correct-response <qti-value> gains a matching space-separated id couple.
Clear the question, blank one card of a pair, and give a pair the same text on both sides — three distinct messages appear, one per rule.
Click "Add distractor", click away to close the editor, then reopen the "New distractor" chip — the draft is still there and only lands in the pool on "Save".
Close the editor and reopen it — pair order and within-pair order survive the round trip.
Narrow the window below the small breakpoint — each pair stacks with its number and delete control on one row.

Worth questioning:

buildXML collapses two choices with equal text into one pool entry and bumps its match-max, so an author who deliberately wants two visually identical options gets one. Blank content is exempt, otherwise a freshly added pair could not round-trip.
A distractor is derived from match-max minus the choice's appearances in the correct response, so hand-written XML with a match-max larger than intended silently gains distractors on import.

Screenshots

State	Screenshot
Edit mode
View mode, answers hidden
View mode, answers shown
Validation
Small screen

axe-core (WCAG 2 AA) on the demo page reports one violation: colour contrast on AddListItemButton's label. It reproduces on the unchanged ordering editor, which uses the same shared component.

AI usage

Used Claude Code to implement the plugin test-first against a written plan, following the ordering interaction as the reference. Verified with the Jest suite, pre-commit, manual QA on the QTI demo page, and an axe-core audit.

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

How was this generated?

Ran pre-flight CI checks (lint, format, tests) and verified all pass
Rebased onto the target branch and resolved any conflicts
Reorganized commit history into clean, logical commits
Audited the diff to ensure only issue-relevant files are changed
Built PR body from the repository's PR template with evidence blocks

	🟡 Waiting for feedback Last updated: 2026-09-01 15:11 UTC

AlexVelezLl

@rtibblesbot, from the screenshots, I can see that the padding of the chips is not the same as in the specs, and the colors of the pair rows are not the same as in the specs. Take a closer look at the images in the issue and check that everything is correctly aligned.

rtibblesbot · 2026-08-31T22:14:34Z

@AlexVelezLl Fixed, and I swept every element in the editor against the six mockups rather than only the two you named — eight divergences, all changed:

Pair rows — grey.v_100 → grey.v_50 with a fineLine border; cards now sit on surface instead of inheriting the row tint.
Pair cards — 40px tall with an 8px text inset; were 50px at the editor's default 24px inset.
Chips — padding: 4px 12px with an 8px gap before the delete control; were 0 4px 0 12px, so the × sat flush against the border. Dropping the editor's paragraph margins takes them from 50px to 34px.
Chip fill — a chip inverts against its container: tinted in the distractor pool, white in the shuffled pool. Both were white.
Shuffled pool box — grey.v_100 → grey.v_50.
Correct-answer chip border — green.v_500 → green.v_600, matching the mockup and the choice/ordering editors.
Pair validation message — aligned to the row's left edge; it was indented under the cards.
Copy — Matching pairs, Distractors (optional), Response pool (shuffled), Add distractor and both sublabels, verbatim from the mockups. The branch shipped the plan's provisional wording (Correct pairs, Additional options, Options (shuffled), Add option) — which is also why the labels in the PR body's screenshots don't match what the branch renders. The four below are current.

Two mockup details I left out, both more than styling — say the word and I'll add them:

the SAVE button on the new-distractor editor (the sibling editors commit on type and close via the minimize control)
the Answer placeholder in an empty pair card (TipTapEditor has no placeholder prop)

State	Screenshot
Edit
View, answers shown
Validation
Small screen

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

AlexVelezLl

Just few findings from a high-level overview.

AlexVelezLl · 2026-09-01T13:12:59Z

  },
+
+  associateLabel: {
+    message: 'Connect pairs',


Could you translate it to "Associate" instead?

Renamed to Associate.

AlexVelezLl · 2026-09-01T13:13:38Z

+    message: 'Connect pairs',
+    context: 'Display name for an associate question type shown in the question type selector',
+  },
+  associateDescription: {


Must associate pairs of items, or something similar

Now Learners must associate pairs of items.

AlexVelezLl · 2026-09-01T13:14:34Z

Let's add what we added for choice interaction, and let's prevent the removal of the last pair, also let's disable the remove button if its the last pair.

removePair is a no-op at one pair, matching removeChoice, and the delete button is disabled there. Spec gained that case plus a max-associations block mirroring choice's max-choices one. Checked the branch's other list mutators: removeDistractor is the only sibling, and distractors are optional, so it keeps no floor.

AlexVelezLl · 2026-09-01T13:19:41Z

+
+    it('appends a third pair when the add pair button is clicked', async () => {
+      renderEditor();
+      await fireEvent.click(screen.getByRole('button', { name: tr.$tr('addPairBtn') }));


Let's use userEvent.setup() instead.

Whole editor spec is on userEvent.setup() now — 43 interactions, no fireEvent left under interactions/associate/. It was the only spec on the branch using it; the parse, validate and composable specs call the units directly.

AlexVelezLl · 2026-09-01T13:23:22Z

+    it('appends a second distractor when the add distractor button is clicked', async () => {
+      renderEditor();
+      await fireEvent.click(screen.getByRole('button', { name: tr.$tr('addDistractorBtn') }));
+      expect(
+        screen.getByRole('button', { name: tr.$tr('deleteDistractorBtn', { number: 2 }) }),
+      ).toBeInTheDocument();
+    });


This behavior is incorrect. When the "Add distractor" button is clicked, it should show a TipTapEditor below the distractors pool, and it should be saved when the Save button is clicked.

If focus is lost and tiptap is closed, let's add a small "new distractor" label so that users can come back and edit it until they hit save. Once they hit save, then we can show the add distractor button again.

Reworked. Add distractor opens a TipTap editor below the pool with a Save button; the draft lives outside state, so nothing joins the pool and nothing is emitted until Save. Closing the editor (by clicking a pair, say) leaves a small New distractor chip that reopens it with the written content still there; Save turns it into a chip and brings the Add distractor button back.

Verified in the running editor, not only in jsdom — worth it, because the first version passed its tests and was dead in the browser: the click that opens the draft finishes bubbling after TipTap has mounted its outside-click listener, so the editor closed itself immediately. Add pair had the same bug (the new pair's editor never stayed open). Both add buttons now stop the click.

AlexVelezLl · 2026-09-01T13:38:44Z

+      expect(contentsOf(parse(ASSOCIATE_XML, [decl]).pairs)).toEqual([['Capulet', 'Montague']]);
+    });
+
+    it('drops a pair naming identifiers that only exist on Object.prototype', () => {


It's not clear to me what this tests for, is because these choices are not declared on ASSOCIATE_XML?

Right — constructor/toString are not declared in ASSOCIATE_XML, and the point is that the pool lookup must not resolve them off Object.prototype (it is a Map, not a plain object). Renamed the test to say that and added the reason as a comment on both prototype cases.

AlexVelezLl · 2026-09-01T13:47:10Z

+    it('counts a distractor repeat of paired content towards match-max', () => {
+      const distractors = [{ id: 'choice_zzz00000', content: 'Antonio' }];
+      const root = parseXmlString(build({ ...baseState, distractors }).bodyXml);
+      const antonio = choicesOf(root).filter(el => el.textContent === 'Antonio');
+      expect(antonio).toHaveLength(1);
+      expect(antonio[0].getAttribute('match-max')).toBe('2');
+    });
+
+    it('reassigns the id of a later choice that reuses an id with different content', () => {
+      const pairs = [
+        baseState.pairs[0],
+        [
+          { id: 'choice_aaa11111', content: 'Capulet' },
+          { id: 'choice_ddd44444', content: 'Montague' },
+        ],
+      ];
+      const { bodyXml, responseDeclarations } = build({
+        ...baseState,
+        pairs,
+        distractors: [],
+      });
+      const [capulet] = choicesOf(parseXmlString(bodyXml)).filter(
+        el => el.textContent === 'Capulet',
+      );
+      expect(capulet.getAttribute('identifier')).toMatch(/^choice_/);
+      expect(capulet.getAttribute('identifier')).not.toBe('choice_aaa11111');
+      expect(valuesOf(parseXmlString(responseDeclarations[0]))[1]).toBe(
+        `${capulet.getAttribute('identifier')} choice_ddd44444`,
+      );
+    });


Could you make some permutations of these to test what happens if: the first appearance is repeated, then a following has the same id but different content, etc. Also, lets test that the first appearance keep the id.

Added an id normalization block with four permutations: a repeat carrying a different id (the first id wins, the second never appears), a later choice reusing an id with different content (the first keeps the id), a repeat followed by an id conflict on the same choice (match-max="2" plus a fresh id for the conflict), and a third choice repeating already-reassigned content. Each asserts the pool and the <qti-value> list.

AlexVelezLl · 2026-09-01T13:50:19Z

+  describe('TOO_FEW_PAIRS', () => {
+    it('returns error when there are no pairs at all', () => {
+      expect(errorCodes(validateAssociateInteraction(makeState({ pairs: [] })))).toContain(
+        ValidationError.TOO_FEW_PAIRS,
+      );
+    });


This should test also valid pairs, if there is a pair, but its invalid, then show the too few valid pairs error.

Added: the only pair blank, the only pair holding the same content twice, every pair invalid for a different reason, and one valid pair among invalid ones (no error).

AlexVelezLl · 2026-09-01T13:54:46Z

+    pairedCount.set(id, (pairedCount.get(id) || 0) + 1);
+  }
+
+  const distractors = pool.flatMap(({ id, content, matchMax }) =>


Could we use 'lodash/flatMap' instead?

Done, and the rest of the branch with it — 6 sites: parse.js (3), validate.js (1), the editor (2). No native flat/flatMap left in the associate plugin.

AlexVelezLl · 2026-09-01T14:06:02Z

+  function shuffled(items) {
+    const result = [...items];
+    for (let i = result.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+  }


Could we use lodash/shuffle instead?

Done — the hand-rolled Fisher–Yates is gone.

Splits the single flat pool of <qti-simple-associable-choice> elements into authoring state: `pairs` from the correct response, `distractors` from the match-max capacity the correct response does not consume. buildXML re-merges them, normalizing ids so equal content shares one pool entry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Registering the descriptor does not populate QUESTION_TYPE_LABELS, so QTIItemEditor gets an explicit ASSOCIATE entry — without it every associate item's view-mode header reads "Unknown type". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

rtibblesbot force-pushed the issue-6101-e6feda branch 3 times, most recently from 6e5a1f4 to 2c9fff3 Compare August 31, 2026 16:53

rtibblesbot marked this pull request as ready for review August 31, 2026 16:54

AlexVelezLl requested changes Aug 31, 2026

View reviewed changes

rtibblesbot force-pushed the issue-6101-e6feda branch from e0394dd to 6ce2d00 Compare August 31, 2026 22:18

AlexVelezLl requested changes Sep 1, 2026

View reviewed changes

rtibblesbot and others added 4 commits September 1, 2026 08:06

Add associate interaction descriptor and composable

e5c745f

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Add an associate item to the QTI demo page

366bf77

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

rtibblesbot force-pushed the issue-6101-e6feda branch from 6ce2d00 to 366bf77 Compare September 1, 2026 15:12

Uh oh!

Uh oh!

Conversation

rtibblesbot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

References

Reviewer guidance

Screenshots

AI usage

🟡 Waiting for feedback

Uh oh!

AlexVelezLl left a comment

Choose a reason for hiding this comment

Uh oh!

rtibblesbot commented Aug 31, 2026

Uh oh!

AlexVelezLl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rtibblesbot commented Aug 31, 2026 •

edited

Loading