Merge pull request #1283 from revisit-studies/ew/quanlitative_code

JackWilb · web-flow · commit 0ce425894519 · 2026-06-23T11:42:39.000-06:00
Add qualitative coding download functionality for JSON and CSV
diff --git a/src/analysis/tests/thinkAloudUtils.spec.ts b/src/analysis/tests/thinkAloudUtils.spec.ts
@@ -43,6 +43,25 @@ describe.each([
     expect(initial).toEqual({ participantTags: [], taskTags: {} });
   });
 
+  test('participant/task tag reads only create storage records when requested', async () => {
+    const participant = await storageEngine.initializeParticipantSession({}, configSimple, participantMetadata);
+    const storagePath = `audio/transcriptAndTags/${ownerKey}/${participant.participantId}`;
+
+    const readOnlyDefault = await storageEngine.getParticipantAndTaskTags(ownerKey, participant.participantId);
+    expect(readOnlyDefault).toEqual({ participantTags: [], taskTags: {} });
+
+    // @ts-expect-error using protected method for testing
+    const afterReadOnlyDefault = await storageEngine._getFromStorage(storagePath, 'participantTags');
+    expect(afterReadOnlyDefault).toBeNull();
+
+    const createIfMissingDefault = await storageEngine.getParticipantAndTaskTags(ownerKey, participant.participantId, true);
+    expect(createIfMissingDefault).toEqual({ participantTags: [], taskTags: {} });
+
+    // @ts-expect-error using protected method for testing
+    const afterCreateIfMissing = await storageEngine._getFromStorage(storagePath, 'participantTags');
+    expect(afterCreateIfMissing).toEqual({ participantTags: [], taskTags: {} });
+  });
+
   test('get participant/task tag defaults is stable across repeated reads', async () => {
     const participant = await storageEngine.initializeParticipantSession({}, configSimple, participantMetadata);
 
diff --git a/src/components/downloader/DownloadButtons.tsx b/src/components/downloader/DownloadButtons.tsx
@@ -10,8 +10,27 @@ import { DownloadTidy, download } from './DownloadTidy';
 import { ParticipantDataWithStatus } from '../../storage/types';
 import { useStorageEngine } from '../../storage/storageEngineHooks';
 import { downloadParticipantsAudioZip, downloadParticipantsProvenanceZip, downloadParticipantsScreenRecordingZip } from '../../utils/handleDownloadFiles';
+import { useAuth } from '../../store/hooks/useAuth';
+import type { StorageEngine } from '../../storage/engines/types';
+import { getParticipantQualitativeCodes } from './qualitativeCodes';
+import type { DownloadedQualitativeCodes } from './qualitativeCodes';
 
 type ParticipantDataFetcher = ParticipantDataWithStatus[] | (() => Promise<ParticipantDataWithStatus[]>);
+type ParticipantDataWithQualitativeCodes = ParticipantDataWithStatus & { qualitativeCodes: DownloadedQualitativeCodes };
+
+async function attachQualitativeCodesToParticipants(
+  participants: ParticipantDataWithStatus[],
+  storageEngine: StorageEngine | undefined,
+  authEmail: string,
+): Promise<ParticipantDataWithQualitativeCodes[]> {
+  return Promise.all(participants.map(async (participant) => {
+    const qualitativeCodes = await getParticipantQualitativeCodes(storageEngine, authEmail, participant);
+    return {
+      ...participant,
+      qualitativeCodes,
+    };
+  }));
+}
 
 export function DownloadButtons({
   visibleParticipants, studyId, gap, fileName, hasAudio, hasScreenRecording,
@@ -22,6 +41,7 @@ export function DownloadButtons({
   const [loadingAudio, setLoadingAudio] = useState(false);
   const [loadingScreenRecording, setLoadingScreenRecording] = useState(false);
   const { storageEngine } = useStorageEngine();
+  const auth = useAuth();
 
   const fetchParticipants = async () => {
     const currParticipants = typeof visibleParticipants === 'function' ? await visibleParticipants() : visibleParticipants;
@@ -30,8 +50,13 @@ export function DownloadButtons({
 
   const handleDownloadJSON = async () => {
     const currParticipants = await fetchParticipants();
+    const participantsWithQualitativeCodes = await attachQualitativeCodesToParticipants(
+      currParticipants,
+      storageEngine,
+      auth.user.user?.email || 'temp',
+    );
     const currFileName = fileName ? `${fileName}.json` : `${studyId}_all.json`;
-    download(JSON.stringify(currParticipants, null, 2), currFileName);
+    download(JSON.stringify(participantsWithQualitativeCodes, null, 2), currFileName);
   };
 
   const handleOpenTidy = async () => {
diff --git a/src/components/downloader/DownloadTidy.tsx b/src/components/downloader/DownloadTidy.tsx
@@ -23,10 +23,13 @@ import { StorageEngine } from '../../storage/engines/types';
 import { useStorageEngine } from '../../storage/storageEngineHooks';
 import { FirebaseStorageEngine } from '../../storage/engines/FirebaseStorageEngine';
 import { useAsync } from '../../store/hooks/useAsync';
+import { useAuth } from '../../store/hooks/useAuth';
 import { getCleanedDuration } from '../../utils/getCleanedDuration';
 import { showNotification } from '../../utils/notifications';
 import { studyComponentToIndividualComponent } from '../../utils/handleComponentInheritance';
 import { parseConditionParam } from '../../utils/handleConditionLogic';
+import { getAnswerIdentifier, getParticipantQualitativeCodes } from './qualitativeCodes';
+import type { DownloadedQualitativeCodes } from './qualitativeCodes';
 
 const OPTIONAL_COMMON_PROPS = [
   'condition',
@@ -50,6 +53,8 @@ const OPTIONAL_COMMON_PROPS = [
   'responseMax',
   'configHash',
   'metaData',
+  'participantTags',
+  'taskTags',
 ] as const;
 
 const REQUIRED_PROPS = [
@@ -105,23 +110,25 @@ function participantDataToRows(
   properties: Property[],
   studyConfig?: StudyConfig,
   transcripts?: Record<string, string | null>,
+  qualitativeCodes?: DownloadedQualitativeCodes,
 ): [TidyRow[], string[]] {
   const percentComplete = ((Object.entries(participant.answers).filter(([_, entry]) => entry.endTime !== -1).length / (Object.entries(participant.answers).length)) * 100).toFixed(2);
   const newHeaders = new Set<string>();
   const participantConditions = parseConditionParam(participant.conditions ?? participant.searchParams?.condition);
   const conditionValue = participantConditions.length > 0 ? participantConditions.join(',') : 'default';
   const metaData = JSON.stringify(participant.metadata);
+  const participantQualitativeTags = JSON.stringify(qualitativeCodes?.participantTags ?? []);
 
   return [[
-    {
+    ...(properties.includes('participantTags') ? [{
       participantId: participant.participantId,
       trialId: 'participantTags',
       trialOrder: null,
       responseId: 'participantTags',
-      answer: JSON.stringify(participant.participantTags),
+      answer: participantQualitativeTags,
       ...(properties.includes('condition') ? { condition: conditionValue } : {}),
       ...(properties.includes('stage') ? { stage: participant.stage } : {}),
-    },
+    }] : []),
     ...(properties.includes('metaData') ? [{
       participantId: participant.participantId,
       trialId: 'metaData',
@@ -137,6 +144,8 @@ function participantDataToRows(
       const { trialOrder } = trialAnswer;
       const trialConfig = studyConfig?.components?.[trialId];
       const completeComponent = trialConfig && studyConfig ? studyComponentToIndividualComponent(trialConfig, studyConfig) : undefined;
+      const identifier = getAnswerIdentifier(trialAnswer);
+      const taskQualitativeTags = JSON.stringify(qualitativeCodes?.taskTags[identifier] ?? []);
 
       const duration = trialAnswer.endTime === -1 ? undefined : trialAnswer.endTime - trialAnswer.startTime;
       const cleanedDuration = getCleanedDuration(trialAnswer);
@@ -189,8 +198,10 @@ function participantDataToRows(
         if (properties.includes('answer')) {
           tidyRow.answer = typeof value === 'object' ? JSON.stringify(value) : value;
         }
+        if (properties.includes('taskTags')) {
+          tidyRow.taskTags = taskQualitativeTags;
+        }
         if (properties.includes('transcript')) {
-          const identifier = trialAnswer.identifier || `${trialId}_${trialOrder}`;
           tidyRow.transcript = transcripts?.[`${participant.participantId}_${identifier}`] ?? undefined;
         }
         if (properties.includes('correctAnswer')) {
@@ -261,6 +272,7 @@ export async function getTableData(
   storageEngine: StorageEngine | undefined,
   studyId: string,
   hasAudio?: boolean,
+  authEmail = 'temp',
 ) {
   if (!storageEngine) {
     return { header: [], rows: [], missingConfigCount: 0 };
@@ -280,7 +292,7 @@ export async function getTableData(
       .filter((answer) => ((answer?.endTime ?? -1) > 0) || ((answer?.startTime ?? -1) > 0))
       .map((answer) => ({ answer, participantId: p.participantId })));
     const tasks = allAnswers.map(({ answer, participantId }) => async () => {
-      const identifier = answer.identifier || `${answer.componentName}_${answer.trialOrder}`;
+      const identifier = getAnswerIdentifier(answer);
       const key = `${participantId}_${identifier}`;
 
       try {
@@ -300,14 +312,19 @@ export async function getTableData(
   });
   const header = combinedProperties
     .filter((p) => p !== 'condition' || hasCondition)
-    .filter((p) => p !== 'metaData');
+    .filter((p) => p !== 'metaData')
+    .filter((p) => p !== 'participantTags');
   const allData = await Promise.all(data.map(async (participant) => {
     const participantConfig = allConfigs[participant.participantConfigHash];
+    const qualitativeCodes = selectedProperties.includes('participantTags') || selectedProperties.includes('taskTags')
+      ? await getParticipantQualitativeCodes(storageEngine, authEmail, participant)
+      : undefined;
     const partDataToRows = await participantDataToRows(
       participant,
       combinedProperties,
       hasStoredStudyConfig(participantConfig) ? participantConfig : undefined,
       transcripts,
+      qualitativeCodes,
     );
 
     return partDataToRows;
@@ -351,6 +368,7 @@ export function DownloadTidy({
   const [isDownloading, setIsDownloading] = useState(false);
   const [downloadProgress, setDownloadProgress] = useState(0);
   const [showTranscriptWarning, setShowTranscriptWarning] = useState(false);
+  const auth = useAuth();
 
   const [selectedProperties, setSelectedProperties] = useState<Array<OptionalProperty>>([
     'condition',
@@ -369,7 +387,7 @@ export function DownloadTidy({
   ]);
 
   const { storageEngine } = useStorageEngine();
-  const { value: tableData, status: tableDataStatus, error: tableError } = useAsync(getTableData, [selectedProperties, data, storageEngine, studyId, hasAudio]);
+  const { value: tableData, status: tableDataStatus, error: tableError } = useAsync(getTableData, [selectedProperties, data, storageEngine, studyId, hasAudio, auth.user.user?.email || 'temp']);
   const isFirebase = storageEngine?.getEngine() === 'firebase';
   const transcriptAvailable = isFirebase && !!hasAudio;
   const selectedParticipantCount = data.length;
diff --git a/src/components/downloader/qualitativeCodes.ts b/src/components/downloader/qualitativeCodes.ts
@@ -0,0 +1,76 @@
+import type { ParticipantTags, Tag } from '../../analysis/individualStudy/thinkAloud/types';
+import type { StorageEngine } from '../../storage/engines/types';
+import type { ParticipantDataWithStatus } from '../../storage/types';
+import type { StoredAnswer } from '../../store/types';
+import { parseTrialOrder } from '../../utils/parseTrialOrder';
+
+export type DownloadedTag = Pick<Tag, 'id' | 'name'>;
+
+export interface DownloadedQualitativeCodes {
+  participantTags: DownloadedTag[];
+  taskTags: Record<string, DownloadedTag[]>;
+}
+
+const removeTagColor = ({ id, name }: Tag): DownloadedTag => ({ id, name });
+
+export const createEmptyQualitativeCodes = (): DownloadedQualitativeCodes => ({
+  participantTags: [],
+  taskTags: {},
+});
+
+export function getAnswerIdentifier(answer: Pick<StoredAnswer, 'componentName' | 'identifier' | 'trialOrder'>) {
+  return answer.identifier || `${answer.componentName}_${answer.trialOrder}`;
+}
+
+export function normalizeQualitativeCodes(
+  qualitativeCodes: ParticipantTags | undefined,
+  participant: ParticipantDataWithStatus,
+): DownloadedQualitativeCodes {
+  const storedTaskTags = Object.fromEntries(
+    Object.entries(qualitativeCodes?.taskTags ?? {}).map(([identifier, tags]) => [identifier, tags.map(removeTagColor)]),
+  );
+  const taskTags: DownloadedQualitativeCodes['taskTags'] = {};
+
+  Object.values(participant.answers).sort((a, b) => {
+    const aOrder = parseTrialOrder(a.trialOrder);
+    const bOrder = parseTrialOrder(b.trialOrder);
+    const aStep = aOrder.step ?? Number.MAX_SAFE_INTEGER;
+    const bStep = bOrder.step ?? Number.MAX_SAFE_INTEGER;
+    const stepDiff = aStep - bStep;
+
+    if (stepDiff !== 0) {
+      return stepDiff;
+    }
+
+    return (aOrder.funcIndex ?? -1) - (bOrder.funcIndex ?? -1);
+  }).forEach((answer) => {
+    const identifier = getAnswerIdentifier(answer);
+    taskTags[identifier] = storedTaskTags[identifier] ?? [];
+  });
+
+  Object.entries(storedTaskTags).forEach(([identifier, tags]) => {
+    taskTags[identifier] ??= tags;
+  });
+
+  return {
+    participantTags: qualitativeCodes?.participantTags.map(removeTagColor) ?? [],
+    taskTags,
+  };
+}
+
+export async function getParticipantQualitativeCodes(
+  storageEngine: StorageEngine | undefined,
+  authEmail: string,
+  participant: ParticipantDataWithStatus,
+) {
+  if (!storageEngine) {
+    return normalizeQualitativeCodes(undefined, participant);
+  }
+
+  try {
+    const qualitativeCodes = await storageEngine.getParticipantAndTaskTags(authEmail, participant.participantId, false);
+    return normalizeQualitativeCodes(qualitativeCodes, participant);
+  } catch {
+    return normalizeQualitativeCodes(undefined, participant);
+  }
+}
diff --git a/src/components/downloader/tests/DownloadButtons.spec.tsx b/src/components/downloader/tests/DownloadButtons.spec.tsx
@@ -10,11 +10,27 @@ import { DownloadButtons } from '../DownloadButtons';
 import { download } from '../DownloadTidy';
 import { downloadParticipantsAudioZip, downloadParticipantsScreenRecordingZip } from '../../../utils/handleDownloadFiles';
 import type { ParticipantDataWithStatus } from '../../../storage/types';
+import { makeStoredAnswer } from '../../../tests/utils';
 
 // ── mocks ─────────────────────────────────────────────────────────────────────
 
+const mockState = vi.hoisted(() => ({
+  storageEngine: {
+    getEngine: vi.fn(() => 'firebase'),
+    getParticipantAndTaskTags: vi.fn(),
+  },
+}));
+
 vi.mock('../../../storage/storageEngineHooks', () => ({
-  useStorageEngine: () => ({ storageEngine: { getEngine: () => 'firebase' } }),
+  useStorageEngine: () => ({ storageEngine: mockState.storageEngine }),
+}));
+
+vi.mock('../../../store/hooks/useAuth', () => ({
+  useAuth: () => ({
+    user: {
+      user: { email: 'analyst@example.com' },
+    },
+  }),
 }));
 
 vi.mock('@mantine/hooks', () => ({
@@ -59,6 +75,11 @@ const baseProps = {
   visibleParticipants: [] as ParticipantDataWithStatus[],
 };
 
+beforeEach(() => {
+  mockState.storageEngine.getEngine.mockReturnValue('firebase');
+  mockState.storageEngine.getParticipantAndTaskTags.mockResolvedValue({ participantTags: [], taskTags: {} });
+});
+
 // ── tests ─────────────────────────────────────────────────────────────────────
 
 describe('DownloadButtons', () => {
@@ -169,6 +190,43 @@ describe('DownloadButtons click handlers', () => {
     );
   });
 
+  test('JSON button includes TA participant and task qualitative codes', async () => {
+    const participantTag = { id: 'participant-code', name: 'Hesitation', color: '#ff0000' };
+    const taskTag = { id: 'task-code', name: 'Chart Reading', color: '#0000ff' };
+    const participantWithAnswers = {
+      ...participant,
+      answers: {
+        trial_1: makeStoredAnswer({ identifier: 'trial_1', trialOrder: '1' }),
+        trial_0: makeStoredAnswer({ identifier: 'trial_0', trialOrder: '0' }),
+      },
+    };
+    mockState.storageEngine.getParticipantAndTaskTags.mockResolvedValueOnce({
+      participantTags: [participantTag],
+      taskTags: {
+        trial_1: [],
+        trial_0: [taskTag],
+      },
+    });
+
+    await act(async () => {
+      render(<DownloadButtons studyId="test-study" visibleParticipants={[participantWithAnswers]} />);
+    });
+
+    const jsonBtn = screen.getByText('json-icon').closest('button')!;
+    await act(async () => { fireEvent.click(jsonBtn); });
+
+    expect(mockState.storageEngine.getParticipantAndTaskTags).toHaveBeenCalledWith('analyst@example.com', 'p1', false);
+    const exportedJson = vi.mocked(download).mock.calls[0][0];
+    expect(JSON.parse(exportedJson)[0].qualitativeCodes).toEqual({
+      participantTags: [{ id: participantTag.id, name: participantTag.name }],
+      taskTags: {
+        trial_0: [{ id: taskTag.id, name: taskTag.name }],
+        trial_1: [],
+      },
+    });
+    expect(Object.keys(JSON.parse(exportedJson)[0].qualitativeCodes.taskTags)).toEqual(['trial_0', 'trial_1']);
+  });
+
   test('JSON button uses custom fileName when provided', async () => {
     await act(async () => {
       render(<DownloadButtons studyId="test-study" visibleParticipants={[participant]} fileName="custom" />);
diff --git a/src/components/downloader/tests/DownloadTidy.spec.tsx b/src/components/downloader/tests/DownloadTidy.spec.tsx
diff --git a/src/storage/engines/types.ts b/src/storage/engines/types.ts
