From 7a51c15d34e351f3d61b4dd5b7296b8356e96996 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:33:46 -0500 Subject: [PATCH 01/19] fix(web): date an in-person session when it is submitted, not when the page loaded The Start Session form computed the current date once, at module scope, and used it as the in-person session date, the upper bound for a retrospective date and the reference for the group's minimum age. Every session started later in the same page load was backdated to when the page first opened. Each check now reads the clock when the form is validated, and the in-person default is built at submission. Closes #1675 Co-Authored-By: Claude Opus 5.5 --- .../StartSessionForm/StartSessionForm.tsx | 21 ++++---- .../__tests__/StartSessionForm.test.tsx | 54 +++++++++++++++++++ testing/src/specs/start-session.spec.ts | 23 ++++++++ 3 files changed, 88 insertions(+), 10 deletions(-) diff --git a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx index a001937f2..aeea01ca1 100644 --- a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx +++ b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx @@ -19,7 +19,9 @@ import { z } from 'zod/v4'; import { useSubjectDemographicsLookup } from '@/hooks/useSubjectDemographicsLookup'; import { getValueForLanguage } from '@/utils/language'; -const currentDate = new Date(); +const MILLISECONDS_PER_YEAR = 31556952000; + +const isNotInFuture = (date: Date) => date <= new Date(); type StartSessionFormValues = FormTypes.PartialData; @@ -62,9 +64,6 @@ export const StartSessionForm = ({ const lookupDemographics = useSubjectDemographicsLookup(); const [autofilled, setAutofilled] = useState({}); const latestCustomId = useRef(''); - const minDateOfBirth = currentGroup?.settings.minimumAge - ? new Date(currentDate.getTime() - currentGroup.settings.minimumAge * 31556952000) - : undefined; const scopeCustomId = (customId: string) => { return encodeScopedSubjectId(customId, { groupName: currentGroup?.name ?? DEFAULT_GROUP_NAME }); @@ -230,8 +229,8 @@ export const StartSessionForm = ({ sessionType: $SessionType.exclude(['REMOTE']), sessionDate: z .date() - .max(currentDate, { message: t('session.errors.assessmentMustBeInPast') }) - .default(currentDate) + .refine(isNotInFuture, { message: t('session.errors.assessmentMustBeInPast') }) + .default(() => new Date()) }) .superRefine((val, ctx) => { if (val.subjectIdentificationMethod === 'CUSTOM_ID') { @@ -287,7 +286,9 @@ export const StartSessionForm = ({ } } } - if (val.subjectDateOfBirth && val.subjectDateOfBirth > currentDate) { + const minimumAge = currentGroup?.settings.minimumAge; + const minDateOfBirth = minimumAge ? new Date(Date.now() - minimumAge * MILLISECONDS_PER_YEAR) : undefined; + if (val.subjectDateOfBirth && !isNotInFuture(val.subjectDateOfBirth)) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: t({ @@ -301,9 +302,9 @@ export const StartSessionForm = ({ ctx.addIssue({ code: z.ZodIssueCode.custom, message: t({ - en: `Subject must be above age of ${currentGroup?.settings.minimumAge}`, - es: `El sujeto debe tener más de ${currentGroup?.settings.minimumAge} años`, - fr: `Le sujet doit avoir au moins ${currentGroup?.settings.minimumAge} ans` + en: `Subject must be above age of ${minimumAge}`, + es: `El sujeto debe tener más de ${minimumAge} años`, + fr: `Le sujet doit avoir au moins ${minimumAge} ans` }), path: ['subjectDateOfBirth'] }); diff --git a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx index 27b424c79..d628d5d6b 100644 --- a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx +++ b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx @@ -440,6 +440,60 @@ describe('StartSessionForm', () => { }); }); + describe('timing', () => { + const DAY = 24 * 60 * 60 * 1000; + + const pageLoadedAt = Date.now(); + + const toDateString = (time: number) => new Date(time).toISOString().slice(0, 10); + + const moveClock = (time: number) => { + vi.useFakeTimers({ toFake: ['Date'] }); + vi.setSystemTime(time); + }; + + const enterSessionDate = (form: HTMLElement, date: string) => { + const input = form.querySelector('[name="sessionDate"]')!; + fireEvent.focus(input); + fireEvent.change(input, { target: { value: date } }); + fireEvent.blur(input); + }; + + afterEach(() => { + vi.useRealTimers(); + }); + + it('should date an in-person session at submission, so a session started later in the same page load is not backdated to when the page opened', async () => { + const startedAt = pageLoadedAt + 2 * 60 * 60 * 1000; + const form = renderForm([]); + typeIdentifier('abc'); + closeIdentifierPopup(); + moveClock(startedAt); + await submitAndSettle(form); + expect(onSubmit.mock.lastCall?.[0].date).toStrictEqual(new Date(startedAt)); + }); + + it('should accept a retrospective date later than when the page opened once that date has passed', async () => { + const form = renderForm([]); + typeIdentifier('abc'); + closeIdentifierPopup(); + fireEvent.change(form.querySelector('[name="sessionType"]')!, { target: { value: 'RETROSPECTIVE' } }); + enterSessionDate(form, toDateString(pageLoadedAt + DAY)); + moveClock(pageLoadedAt + 2 * DAY); + fireEvent.click(submitButton()); + await waitFor(() => expect(onSubmit).toHaveBeenCalled()); + expect(onSubmit.mock.lastCall?.[0].date).toStrictEqual(new Date(toDateString(pageLoadedAt + DAY))); + }); + + it("should accept a date of birth that reaches the group's minimum age only after the page opened", async () => { + const minimumAgeReachedAt = pageLoadedAt - 18 * 31556952000 + 5 * DAY; + const form = renderForm([], groupWithSettings({ minimumAge: 18 }), 'PERSONAL_INFO'); + fillPersonalInfo(form, { dateOfBirth: toDateString(minimumAgeReachedAt), firstName: 'Jane' }); + moveClock(pageLoadedAt + 10 * DAY); + await submitAndSettle(form); + }); + }); + describe('date of birth', () => { const futureDateOfBirth = `${new Date().getFullYear() + 1}-01-01`; diff --git a/testing/src/specs/start-session.spec.ts b/testing/src/specs/start-session.spec.ts index 251c35c10..a56da335c 100644 --- a/testing/src/specs/start-session.spec.ts +++ b/testing/src/specs/start-session.spec.ts @@ -54,6 +54,29 @@ test.describe('start session', () => { await startSessionPage.submitForm(); await expect(startSessionPage.successMessage).toBeVisible(); }); + + // The form used to compute the session date once, when its code first loaded, so every in-person + // session started later in the same page load was backdated to that moment. + test('should date an in-person session when it is submitted, not when the page opened', async ({ + getPageModel, + page, + uniqueId + }) => { + const openedAt = new Date(); + await page.clock.install({ time: openedAt }); + const startSessionPage = await getPageModel('/session/start-session'); + await startSessionPage.selectIdentificationMethod('CUSTOM_ID'); + await startSessionPage.typeSubjectId(`timed-${uniqueId}`); + await startSessionPage.dismissSubjectIdOptions(); + await page.clock.fastForward('02:00:00'); + + const sessionCreated = page.waitForResponse( + (response) => response.url().endsWith('/v1/sessions') && response.request().method() === 'POST' + ); + await startSessionPage.submitForm(); + const session = (await (await sessionCreated).json()) as { date: string }; + expect(new Date(session.date).getTime()).toBeGreaterThanOrEqual(openedAt.getTime() + 2 * 60 * 60 * 1000); + }); }); // A custom id says nothing about the subject behind it, so the form fills in what an existing From 3fcf3cd9bb3d893e66b8f8c10dfb95b3d2bd9b60 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:39:39 -0500 Subject: [PATCH 02/19] feat(web): record the time of day of a retrospective session A retrospective session's date is now a date and time, so the time of collection is kept (for MouseODC, the time of day is a proxy for hormonal variation). The date is required: a blank one used to be read as the moment the form was submitted, and a time typed without a date was lost. Closes #1029 Co-Authored-By: Claude Opus 5.5 --- .../StartSessionForm/StartSessionForm.tsx | 30 ++++-- .../__tests__/StartSessionForm.test.tsx | 97 +++++++++++++++---- apps/web/src/translations/session.json | 6 +- .../3.4-how-to-get-started-with-odc.mdx | 2 +- .../pages/_app/session/start-session.page.ts | 30 ++++-- testing/src/specs/start-session.spec.ts | 24 +++++ 6 files changed, 149 insertions(+), 40 deletions(-) diff --git a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx index aeea01ca1..855cf056c 100644 --- a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx +++ b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx @@ -33,7 +33,7 @@ const selectedCustomId = (values: StartSessionFormValues) => { }; type StartSessionFormData = { - sessionDate: Date; + sessionDate?: Date; sessionType: 'IN_PERSON' | 'RETROSPECTIVE'; subjectDateOfBirth?: Date; subjectFirstName?: string; @@ -198,7 +198,8 @@ export const StartSessionForm = ({ ? { description: t('session.dateAssessed.description'), kind: 'date', - label: t('session.dateAssessed.label') + label: t('session.dateAssessed.label'), + variant: 'datetime' } : null; } @@ -219,7 +220,7 @@ export const StartSessionForm = ({ subjectFirstName: z.string().optional(), subjectLastName: z.string().optional(), subjectIdentificationMethod: $SubjectIdentificationMethod, - // Every check on the identifier and the date of birth lives in the refinement below: zod v4 + // Every check on the identifier and the two dates lives in the refinement below: zod v4 // omits an optional property that failed its own checks from the value it hands the // refinement, which then reads the field as missing and adds a contradictory required-field // error. @@ -227,12 +228,24 @@ export const StartSessionForm = ({ subjectDateOfBirth: z.date().optional(), subjectSex: z.enum(['MALE', 'FEMALE']).optional(), sessionType: $SessionType.exclude(['REMOTE']), - sessionDate: z - .date() - .refine(isNotInFuture, { message: t('session.errors.assessmentMustBeInPast') }) - .default(() => new Date()) + sessionDate: z.date().optional() }) .superRefine((val, ctx) => { + if (val.sessionType === 'RETROSPECTIVE') { + if (!val.sessionDate) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: t('core.form.requiredField'), + path: ['sessionDate'] + }); + } else if (!isNotInFuture(val.sessionDate)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: t('session.errors.assessmentMustBeInPast'), + path: ['sessionDate'] + }); + } + } if (val.subjectIdentificationMethod === 'CUSTOM_ID') { if (!val.subjectId) { ctx.addIssue({ @@ -330,7 +343,8 @@ export const StartSessionForm = ({ subjectId = scopeCustomId(subjectId); } await onSubmit({ - date: sessionDate, + // Only a retrospective session has a date of its own; an in-person one starts now. + date: sessionDate ?? new Date(), groupId: currentGroup?.id ?? null, username: username ?? null, type: sessionType, diff --git a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx index d628d5d6b..1b4698148 100644 --- a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx +++ b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx @@ -2,7 +2,7 @@ import { DEFAULT_GROUP_NAME } from '@opendatacapture/schemas/core'; import type { Group, GroupSettings } from '@opendatacapture/schemas/group'; import { generateSubjectHash } from '@opendatacapture/subject-utils'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'; +import { act, cleanup, fireEvent, getByText, render, screen, waitFor } from '@testing-library/react'; import axios from 'axios'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; @@ -452,13 +452,6 @@ describe('StartSessionForm', () => { vi.setSystemTime(time); }; - const enterSessionDate = (form: HTMLElement, date: string) => { - const input = form.querySelector('[name="sessionDate"]')!; - fireEvent.focus(input); - fireEvent.change(input, { target: { value: date } }); - fireEvent.blur(input); - }; - afterEach(() => { vi.useRealTimers(); }); @@ -473,24 +466,90 @@ describe('StartSessionForm', () => { expect(onSubmit.mock.lastCall?.[0].date).toStrictEqual(new Date(startedAt)); }); - it('should accept a retrospective date later than when the page opened once that date has passed', async () => { + it("should accept a date of birth that reaches the group's minimum age only after the page opened", async () => { + const minimumAgeReachedAt = pageLoadedAt - 18 * 31556952000 + 5 * DAY; + const form = renderForm([], groupWithSettings({ minimumAge: 18 }), 'PERSONAL_INFO'); + fillPersonalInfo(form, { dateOfBirth: toDateString(minimumAgeReachedAt), firstName: 'Jane' }); + moveClock(pageLoadedAt + 10 * DAY); + await submitAndSettle(form); + }); + }); + + describe('retrospective session', () => { + // A fixed local date a year ahead, so the picker opens on a known month and a date frozen when + // the module loaded would lie before every time used here. + const pageOpenedAt = new Date(new Date().getFullYear() + 1, 5, 15, 9, 0, 0); + + const chooseRetrospective = (form: HTMLElement) => { + fireEvent.change(form.querySelector('[name="sessionType"]')!, { target: { value: 'RETROSPECTIVE' } }); + }; + + const pickSessionDay = (day: number) => { + fireEvent.click(screen.getByTestId('datetime-date-trigger')); + fireEvent.click(getByText(screen.getByTestId('datepicker'), String(day))); + }; + + const enterSessionTime = (time: string) => { + fireEvent.change(screen.getByTestId('datetime-time-input'), { target: { value: time } }); + }; + + const renderWithNewIdentifier = () => { const form = renderForm([]); typeIdentifier('abc'); closeIdentifierPopup(); - fireEvent.change(form.querySelector('[name="sessionType"]')!, { target: { value: 'RETROSPECTIVE' } }); - enterSessionDate(form, toDateString(pageLoadedAt + DAY)); - moveClock(pageLoadedAt + 2 * DAY); + chooseRetrospective(form); + return form; + }; + + beforeEach(() => { + vi.useFakeTimers({ toFake: ['Date'] }); + vi.setSystemTime(pageOpenedAt); + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it('should submit the time of day entered for a retrospective session, so the collection time is kept', async () => { + renderWithNewIdentifier(); + pickSessionDay(15); + enterSessionTime('08:30:15'); fireEvent.click(submitButton()); await waitFor(() => expect(onSubmit).toHaveBeenCalled()); - expect(onSubmit.mock.lastCall?.[0].date).toStrictEqual(new Date(toDateString(pageLoadedAt + DAY))); + expect(onSubmit.mock.lastCall?.[0]).toMatchObject({ + date: new Date(pageOpenedAt.getFullYear(), 5, 15, 8, 30, 15), + type: 'RETROSPECTIVE' + }); }); - it("should accept a date of birth that reaches the group's minimum age only after the page opened", async () => { - const minimumAgeReachedAt = pageLoadedAt - 18 * 31556952000 + 5 * DAY; - const form = renderForm([], groupWithSettings({ minimumAge: 18 }), 'PERSONAL_INFO'); - fillPersonalInfo(form, { dateOfBirth: toDateString(minimumAgeReachedAt), firstName: 'Jane' }); - moveClock(pageLoadedAt + 10 * DAY); - await submitAndSettle(form); + it('should accept a retrospective time later than when the page opened once that time has passed', async () => { + renderWithNewIdentifier(); + pickSessionDay(15); + enterSessionTime('10:30:00'); + vi.setSystemTime(new Date(pageOpenedAt.getFullYear(), 5, 15, 11, 0, 0)); + fireEvent.click(submitButton()); + await waitFor(() => expect(onSubmit).toHaveBeenCalled()); + }); + + it('should reject a retrospective time that has not happened yet', async () => { + renderWithNewIdentifier(); + pickSessionDay(15); + enterSessionTime('10:30:00'); + fireEvent.click(submitButton()); + await waitFor(() => { + expect(errorMessages()).toEqual([{ field: 'sessionDate', message: 'The assessment must be in the past' }]); + }); + expect(onSubmit).not.toHaveBeenCalled(); + }); + + it('should reject a retrospective session with no date, rather than dating it when the page loaded', async () => { + renderWithNewIdentifier(); + enterSessionTime('08:30:00'); + fireEvent.click(submitButton()); + await waitFor(() => { + expect(errorMessages()).toEqual([{ field: 'sessionDate', message: 'This field is required' }]); + }); + expect(onSubmit).not.toHaveBeenCalled(); }); }); diff --git a/apps/web/src/translations/session.json b/apps/web/src/translations/session.json index 8b45222d7..8969cac48 100644 --- a/apps/web/src/translations/session.json +++ b/apps/web/src/translations/session.json @@ -8,9 +8,9 @@ }, "dateAssessed": { "description": { - "en": "If the session took place on a date other than today, you can change it here.", - "es": "Si la sesión tuvo lugar en una fecha distinta a hoy, puede modificarla aquí.", - "fr": "Si la session a eu lieu à une autre date qu'aujourd'hui, vous pouvez la modifier ici." + "en": "The date and time the session took place.", + "es": "La fecha y la hora en que tuvo lugar la sesión.", + "fr": "La date et l'heure auxquelles la session a eu lieu." }, "label": { "en": "Date Assessed", diff --git a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx index 87eec2ebd..205aa86b0 100644 --- a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx +++ b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx @@ -100,7 +100,7 @@ Use **Start Session** to begin work with a subject. 3. **Choose the session type** - Use an in-person session for new data collection. Use a retrospective session when entering data that was collected earlier using another system. + Use an in-person session for new data collection; it is dated when it starts. Use a retrospective session when entering data that was collected earlier using another system, and enter the date and time the data was collected. 4. **Confirm the session is active** diff --git a/testing/src/pages/_app/session/start-session.page.ts b/testing/src/pages/_app/session/start-session.page.ts index 05e7590f9..8a7054c9c 100644 --- a/testing/src/pages/_app/session/start-session.page.ts +++ b/testing/src/pages/_app/session/start-session.page.ts @@ -67,16 +67,10 @@ export class StartSessionPage extends AppPage { await this.fillSessionDetails(sex); } - /** A retrospective session dated today, without touching the subject's details. */ + /** A retrospective session dated today at midnight, without touching the subject's details. */ async fillSessionTiming() { - const sessionTypeSelector = this.sessionForm.locator('[name="sessionType"]'); - const sessionDate = this.sessionForm.locator('[name="sessionDate"]'); - - await sessionTypeSelector.selectOption('Retrospective'); - - await sessionDate.waitFor({ state: 'visible' }); - const expectedSessionDate = new Date().toISOString().split('T')[0]!; - await sessionDate.fill(expectedSessionDate); + await this.selectRetrospective(); + await this.pickSessionDay(new Date().getDate()); } /** The subject's date of birth and sex, leaving the session at its in-person default. */ @@ -85,10 +79,28 @@ export class StartSessionPage extends AppPage { await this.sexField.selectOption(sex); } + /** A day of the month the date picker opens on, which is the browser's current month. */ + async pickSessionDay(day: number) { + await this.sessionForm.getByTestId('datetime-date-trigger').click(); + await this.$ref + .getByTestId('datepicker') + .getByRole('button', { exact: true, name: String(day) }) + .click(); + } + async selectIdentificationMethod(methodName: string) { await this.selectField.selectOption(methodName); } + async selectRetrospective() { + await this.sessionForm.locator('[name="sessionType"]').selectOption('Retrospective'); + } + + /** The time of day of a retrospective session, as `HH:MM:SS`. */ + async setSessionTime(time: string) { + await this.sessionForm.getByTestId('datetime-time-input').fill(time); + } + /** An identifier already in use by a subject in the current group, offered in the popup. */ subjectIdOption(identifier: string) { return this.$ref.getByTestId(`subjectId-combobox-item-${identifier}`); diff --git a/testing/src/specs/start-session.spec.ts b/testing/src/specs/start-session.spec.ts index a56da335c..fdd515c71 100644 --- a/testing/src/specs/start-session.spec.ts +++ b/testing/src/specs/start-session.spec.ts @@ -79,6 +79,30 @@ test.describe('start session', () => { }); }); +// The date picker opens on the browser's current month, so the clock is fixed to a known day; the +// timezone makes the stored instant, which is what the API receives, the same wherever the suite runs. +test.describe('retrospective session time', () => { + test.use({ timezoneId: 'America/Toronto' }); + + test('should keep the time of day entered for a retrospective session', async ({ getPageModel, page, uniqueId }) => { + await page.clock.install({ time: new Date('2025-06-20T16:00:00Z') }); + const startSessionPage = await getPageModel('/session/start-session'); + await startSessionPage.selectIdentificationMethod('CUSTOM_ID'); + await startSessionPage.typeSubjectId(`retro-${uniqueId}`); + await startSessionPage.dismissSubjectIdOptions(); + await startSessionPage.selectRetrospective(); + await startSessionPage.pickSessionDay(10); + await startSessionPage.setSessionTime('14:30:00'); + + const sessionCreated = page.waitForRequest( + (request) => request.url().endsWith('/v1/sessions') && request.method() === 'POST' + ); + await startSessionPage.submitForm(); + expect((await sessionCreated).postDataJSON()).toMatchObject({ date: '2025-06-10T18:30:00.000Z' }); + await expect(startSessionPage.successMessage).toBeVisible(); + }); +}); + // A custom id says nothing about the subject behind it, so the form fills in what an existing // subject already records. An admin with no group has their custom ids scoped as `root$`. test.describe('existing subject details', () => { From 2cbbecb8566bd0b26304b9bad1d834de7a837264 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:42:53 -0500 Subject: [PATCH 03/19] fix(api): export when each record and session was collected, with the time of day The export projected each row's timestamp from the day the record was inserted, so a retrospective session, a bulk upload or a remote assignment exported with the wrong date, and every row lost its time. It now takes the record's own date, and both it and the session date keep their full ISO timestamp. Closes #1717 Co-Authored-By: Claude Opus 5.5 --- .../instrument-records.service.test.ts | 22 +++++++++++++ .../instrument-records.service.ts | 14 ++------ testing/src/specs/datahub.spec.ts | 33 +++++++++++++++++++ 3 files changed, 57 insertions(+), 12 deletions(-) diff --git a/apps/api/src/instrument-records/__tests__/instrument-records.service.test.ts b/apps/api/src/instrument-records/__tests__/instrument-records.service.test.ts index 04084bb5b..7df0322fa 100644 --- a/apps/api/src/instrument-records/__tests__/instrument-records.service.test.ts +++ b/apps/api/src/instrument-records/__tests__/instrument-records.service.test.ts @@ -971,6 +971,28 @@ describe('InstrumentRecordsService', () => { expect(projectStage.$project.session.user.username).toBe('$sessionUser.username'); }); + // `$dateToString` without a format gives a full ISO timestamp, so the time of collection survives + // and two records collected on one day stay distinguishable. + it('should export the record collection date as the timestamp, not the insertion date', async () => { + instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]); + + await instrumentRecordsService.exportRecords({}, { ability: createAppAbility([]) }); + + const [{ pipeline }] = instrumentRecordModel.aggregateRaw.mock.lastCall as [{ pipeline: any[] }]; + const projectStage = pipeline.find((stage) => stage.$project); + expect(projectStage.$project.date).toStrictEqual({ $dateToString: { date: '$date' } }); + }); + + it('should export the session date with its time of day, so a session started at a known time keeps it', async () => { + instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]); + + await instrumentRecordsService.exportRecords({}, { ability: createAppAbility([]) }); + + const [{ pipeline }] = instrumentRecordModel.aggregateRaw.mock.lastCall as [{ pipeline: any[] }]; + const projectStage = pipeline.find((stage) => stage.$project); + expect(projectStage.$project.session.date).toStrictEqual({ $dateToString: { date: '$session.date' } }); + }); + it('should match only the requested group in the aggregation, so a scoped export reads no other group', async () => { instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]); diff --git a/apps/api/src/instrument-records/instrument-records.service.ts b/apps/api/src/instrument-records/instrument-records.service.ts index d3c99bcc1..e7170427e 100644 --- a/apps/api/src/instrument-records/instrument-records.service.ts +++ b/apps/api/src/instrument-records/instrument-records.service.ts @@ -649,12 +649,7 @@ export class InstrumentRecordsService { { $project: { computedMeasures: 1, - date: { - $dateToString: { - date: '$createdAt', - format: '%Y-%m-%d' - } - }, + date: { $dateToString: { date: '$date' } }, // `$ifNull` for the same reason as in `summarizeRecords`: `$toString` of a missing field is // itself missing, so a record belonging to no group would drop `groupId` from the row // entirely and arrive as undefined behind a type that says it is a string. @@ -665,12 +660,7 @@ export class InstrumentRecordsService { instrumentId: 1, seriesInstrumentId: { $ifNull: ['$seriesInstrumentId', null] }, session: { - date: { - $dateToString: { - date: '$session.date', - format: '%Y-%m-%d' - } - }, + date: { $dateToString: { date: '$session.date' } }, id: { $toString: '$session._id' }, diff --git a/testing/src/specs/datahub.spec.ts b/testing/src/specs/datahub.spec.ts index 663a096a6..94a3869f1 100644 --- a/testing/src/specs/datahub.spec.ts +++ b/testing/src/specs/datahub.spec.ts @@ -121,3 +121,36 @@ test.describe('data hub', () => { await expect(datahubPage.rows).toHaveCount(1); }); }); + +test.describe('data hub export', () => { + // The export used to date each row by the day the record was inserted, which loses both the + // collection date of anything entered later and the time of day of everything. + test('should export the collection date and time of each record and its session', async ({ + api, + isolatedGroupManager, + page, + uniqueId + }) => { + const group = await isolatedGroupManager(); + const instrumentId = await api.findInstrumentIdByName('DNP_HAPPINESS_QUESTIONNAIRE'); + const collectedAt = '2024-01-15T10:30:00.000Z'; + await api.uploadRecords(group.id, instrumentId, [ + { data: HAPPINESS_RECORD, date: new Date(collectedAt), subjectId: `dated-${uniqueId}` } + ]); + + const datahubPage = new DatahubPage(page); + await datahubPage.goto('/datahub/subjects'); + await expect(datahubPage.rows).toHaveCount(1); + + const download = await datahubPage.exportAs('JSON'); + const payload = JSON.parse(await readFile(await download.path(), 'utf8')) as { + sessionDate: string; + timestamp: string; + }[]; + + expect(payload.length).toBeGreaterThan(0); + for (const row of payload) { + expect(row).toMatchObject({ sessionDate: collectedAt, timestamp: collectedAt }); + } + }); +}); From d5d749dc793a6f3bddae252cba6fbc9e5c67ad7b Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 11:10:27 -0500 Subject: [PATCH 04/19] feat: let a group require a form to be completed when a session starts A group manager can choose one form instrument as the group's Session Instrument. Start Session then shows that form after the session details, with a Back control, and the session is created only once the form is submitted: POST /v1/sessions carries the answers and creates the session and a record of them, dated as the session is, or neither. If the record fails to save, the session is deleted, and so is the subject if this request created it. The server refuses a session in such a group without the answers, and answers for a group that requires none. The setting follows a new edition of the form once that edition is saved, an update that would take the form away from the group is refused, and a group is never created with one. The gateway synchronizer, CSV upload and demo seeding create sessions in process and are not asked for it. The group's manage page now reads the group fresh rather than as it was at sign-in, since a save sends back every setting it was seeded with and so could undo a change made since. Refs #1546 Co-Authored-By: Claude Opus 5.5 --- .../docs/architecture/auth-and-permissions.md | 4 + apps/api/prisma/schema.prisma | 2 + .../groups/__tests__/groups.service.test.ts | 72 ++++++- apps/api/src/groups/groups.module.ts | 3 + apps/api/src/groups/groups.service.ts | 52 ++++- .../instrument-records.service.ts | 36 ++-- .../__tests__/instruments.service.test.ts | 32 +++ .../src/instruments/instruments.service.ts | 42 ++-- apps/api/src/main.ts | 2 + .../__tests__/sessions.controller.test.ts | 13 -- apps/api/src/sessions/sessions.controller.ts | 11 +- .../start-session.controller.test.ts | 38 ++++ .../__tests__/start-session.service.test.ts | 196 ++++++++++++++++++ .../start-session/start-session.controller.ts | 25 +++ .../src/start-session/start-session.module.ts | 19 ++ .../start-session/start-session.service.ts | 81 ++++++++ .../__tests__/subjects.service.test.ts | 8 + apps/api/src/subjects/subjects.service.ts | 8 + apps/api/test/helpers.ts | 11 +- .../suites/10-session-instrument.suite.ts | 153 ++++++++++++++ .../SessionInstrumentStep.tsx | 40 ++++ .../__tests__/SessionInstrumentStep.test.tsx | 58 ++++++ .../components/SessionInstrumentStep/index.ts | 1 + .../__tests__/useUpdateGroupMutation.test.ts | 8 +- .../web/src/hooks/useCreateSessionMutation.ts | 4 +- apps/web/src/hooks/useUpdateGroupMutation.ts | 9 +- .../_app/group/__tests__/manage.test.tsx | 134 +++++++++++- apps/web/src/routes/_app/group/manage.tsx | 129 ++++++++---- .../session/__tests__/start-session.test.tsx | 138 ++++++++++++ .../src/routes/_app/session/start-session.tsx | 67 +++++- .../3.4-how-to-get-started-with-odc.mdx | 10 +- .../schemas/src/group/__tests__/group.test.ts | 13 +- packages/schemas/src/group/group.ts | 5 +- packages/schemas/src/session/session.ts | 8 +- .../pages/_app/session/start-session.page.ts | 6 + testing/src/specs/start-session.spec.ts | 51 +++++ testing/src/support/api-client.ts | 11 +- 37 files changed, 1378 insertions(+), 122 deletions(-) create mode 100644 apps/api/src/start-session/__tests__/start-session.controller.test.ts create mode 100644 apps/api/src/start-session/__tests__/start-session.service.test.ts create mode 100644 apps/api/src/start-session/start-session.controller.ts create mode 100644 apps/api/src/start-session/start-session.module.ts create mode 100644 apps/api/src/start-session/start-session.service.ts create mode 100644 apps/api/test/suites/10-session-instrument.suite.ts create mode 100644 apps/web/src/components/SessionInstrumentStep/SessionInstrumentStep.tsx create mode 100644 apps/web/src/components/SessionInstrumentStep/__tests__/SessionInstrumentStep.test.tsx create mode 100644 apps/web/src/components/SessionInstrumentStep/index.ts diff --git a/.agents/docs/architecture/auth-and-permissions.md b/.agents/docs/architecture/auth-and-permissions.md index dedd85c91..321103650 100644 --- a/.agents/docs/architecture/auth-and-permissions.md +++ b/.agents/docs/architecture/auth-and-permissions.md @@ -50,6 +50,10 @@ route. `ADMIN_ONLY` guard; and `InstrumentsService.findBundleById` called without a `currentUser`, which the API's gateway module does to resolve an assignment's bundle. That parameter is optional for this reason, so a new call site that omits it compiles and reads every group's instruments. +`StartSessionService` rolls back unscoped: when the record of a session instrument fails to save, +it deletes the session it just created and, if `SubjectsService.exists` (a boolean, unscoped +because a scoped lookup would miss a subject in another group) found no subject beforehand, the +subject too. `SessionsService.createMany` rolls back the same way. ## Layer 2: row scoping diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index fa8598208..f8c0e7acd 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -107,6 +107,8 @@ type GroupSettings { idValidationRegexErrorMessage LocalizedString? subjectIdDisplayLength Int? minimumAge Int? + // A form instrument that must be completed to start a session in the group, if any. + sessionInstrumentId String? } // Mirrors $LocalizedString in @opendatacapture/schemas/core; each field is optional so diff --git a/apps/api/src/groups/__tests__/groups.service.test.ts b/apps/api/src/groups/__tests__/groups.service.test.ts index 0728a6657..26f543ff8 100644 --- a/apps/api/src/groups/__tests__/groups.service.test.ts +++ b/apps/api/src/groups/__tests__/groups.service.test.ts @@ -9,6 +9,7 @@ import { beforeEach, describe, expect, it } from 'vitest'; import { AuditLogger } from '@/audit/audit.logger'; import { createAppAbility } from '@/auth/ability.utils'; +import { InstrumentsService } from '@/instruments/instruments.service'; import { GroupsService } from '../groups.service'; @@ -30,6 +31,7 @@ describe('GroupsService', () => { let groupsService: GroupsService; let groupModel: MockedInstance>; let instrumentModel: MockedInstance>; + let instrumentsService: MockedInstance; beforeEach(async () => { const moduleRef = await Test.createTestingModule({ @@ -37,13 +39,15 @@ describe('GroupsService', () => { GroupsService, MockFactory.createForModelToken(getModelToken('Group')), MockFactory.createForModelToken(getModelToken('Instrument')), - MockFactory.createForService(AuditLogger) + MockFactory.createForService(AuditLogger), + MockFactory.createForService(InstrumentsService) ] }).compile(); auditLogger = moduleRef.get(AuditLogger); groupModel = moduleRef.get(getModelToken('Group')); instrumentModel = moduleRef.get(getModelToken('Instrument')); groupsService = moduleRef.get(GroupsService); + instrumentsService = moduleRef.get(InstrumentsService); instrumentModel.findMany.mockResolvedValue([]); }); @@ -335,6 +339,72 @@ describe('GroupsService', () => { }); }); + describe('updateById with a session instrument', () => { + const groupRequiring = (sessionInstrumentId: null | string) => ({ + accessibleInstrumentIds: ['form-1', 'form-2'], + name: 'Test Group', + settings: { sessionInstrumentId } + }); + + const accessibleInstruments = (...ids: string[]) => { + instrumentModel.findMany.mockResolvedValueOnce(ids.map((id) => ({ id }))); + }; + + it("should refuse an update dropping the session instrument from the group's instruments, even one not naming the setting", async () => { + groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1')); + accessibleInstruments('form-2'); + await expect(groupsService.updateById('123', { accessibleInstrumentIds: ['form-2'] })).rejects.toThrow( + /before removing instrument 'form-1'/ + ); + expect(groupModel.update).not.toHaveBeenCalled(); + }); + + it('should refuse a session instrument the group cannot access, saying so rather than asking to remove it', async () => { + groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null)); + const update = groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-3' } }); + await expect(update).rejects.toBeInstanceOf(BadRequestException); + await expect(update).rejects.toThrow(/instrument 'form-3' is not$/); + expect(groupModel.update).not.toHaveBeenCalled(); + }); + + it('should refuse a session instrument that is not a form, since only a form is rendered when a session starts', async () => { + groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null)); + instrumentsService.findById.mockResolvedValueOnce({ kind: 'INTERACTIVE' }); + await expect( + groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } }) + ).rejects.toBeInstanceOf(BadRequestException); + expect(groupModel.update).not.toHaveBeenCalled(); + }); + + it("should look the new session instrument up within the caller's ability and the group", async () => { + const ability = createAppAbility([{ action: 'manage', subject: 'all' }]); + groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null)); + instrumentsService.findById.mockResolvedValueOnce({ kind: 'FORM' }); + await groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } }, { ability }); + expect(instrumentsService.findById).toHaveBeenCalledWith('form-1', { ability }, ['123']); + expect(groupModel.update.mock.lastCall?.[0]).toMatchObject({ + data: { settings: { sessionInstrumentId: 'form-1' } } + }); + }); + + it('should accept dropping the session instrument from the group once the setting is cleared in the same update', async () => { + groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1')); + accessibleInstruments('form-2'); + await groupsService.updateById('123', { + accessibleInstrumentIds: ['form-2'], + settings: { sessionInstrumentId: null } + }); + expect(groupModel.update.mock.lastCall?.[0]).toMatchObject({ data: { settings: { sessionInstrumentId: null } } }); + }); + + it('should not look the session instrument up again when the update leaves it as it was', async () => { + groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1')); + await groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } }); + expect(instrumentsService.findById).not.toHaveBeenCalled(); + expect(groupModel.update).toHaveBeenCalled(); + }); + }); + describe('findAll', () => { it('should return the array returned by the group model', async () => { groupModel.findMany.mockResolvedValueOnce([{ name: 'Test Group' }]); diff --git a/apps/api/src/groups/groups.module.ts b/apps/api/src/groups/groups.module.ts index 4524965a6..7b713a980 100644 --- a/apps/api/src/groups/groups.module.ts +++ b/apps/api/src/groups/groups.module.ts @@ -1,11 +1,14 @@ import { Module } from '@nestjs/common'; +import { InstrumentsModule } from '@/instruments/instruments.module'; + import { GroupsController } from './groups.controller'; import { GroupsService } from './groups.service'; @Module({ controllers: [GroupsController], exports: [GroupsService], + imports: [InstrumentsModule], providers: [GroupsService] }) export class GroupsModule {} diff --git a/apps/api/src/groups/groups.service.ts b/apps/api/src/groups/groups.service.ts index 347207c65..3af5040e6 100644 --- a/apps/api/src/groups/groups.service.ts +++ b/apps/api/src/groups/groups.service.ts @@ -9,13 +9,15 @@ import { PrismaClientKnownRequestError } from '@prisma/client/runtime/library'; import { AuditLogger } from '@/audit/audit.logger'; import { accessibleQuery } from '@/auth/ability.utils'; import type { EntityOperationOptions } from '@/core/types'; +import { InstrumentsService } from '@/instruments/instruments.service'; @Injectable() export class GroupsService { constructor( @InjectModel('Group') private readonly groupModel: Model<'Group'>, @InjectModel('Instrument') private readonly instrumentModel: Model<'Instrument'>, - private readonly auditLogger: AuditLogger + private readonly auditLogger: AuditLogger, + private readonly instrumentsService: InstrumentsService ) {} async archiveById(id: string, currentUser: RequestUser) { @@ -124,6 +126,15 @@ export class GroupsService { }); validInstrumentIds = existingInstruments.map(({ id }) => id); } + await this.validateSessionInstrument( + { + accessibleInstrumentIds: validInstrumentIds ?? group.accessibleInstrumentIds, + groupId: id, + sessionInstrumentId: settings?.sessionInstrumentId, + storedSessionInstrumentId: group.settings.sessionInstrumentId + }, + { ability } + ); try { return await this.groupModel.update({ @@ -204,4 +215,43 @@ export class GroupsService { throw new BadRequestException(`No email template with id '${nextActiveId}' exists in this group`); } } + + /** + * Every update is checked, not only one naming the session instrument: removing the instrument from + * the group's accessible list would otherwise leave every Start Session in the group requiring a + * form no one in it can open. + */ + private async validateSessionInstrument( + { + accessibleInstrumentIds, + groupId, + sessionInstrumentId, + storedSessionInstrumentId + }: { + accessibleInstrumentIds: string[]; + groupId: string; + sessionInstrumentId: null | string | undefined; + storedSessionInstrumentId: null | string | undefined; + }, + options: EntityOperationOptions + ): Promise { + // `undefined` leaves the stored value alone; `null` removes it. + const nextSessionInstrumentId = sessionInstrumentId === undefined ? storedSessionInstrumentId : sessionInstrumentId; + if (!nextSessionInstrumentId) { + return; + } + if (!accessibleInstrumentIds.includes(nextSessionInstrumentId)) { + throw new BadRequestException( + nextSessionInstrumentId === storedSessionInstrumentId + ? `The group's Session Instrument must be one of its accessible instruments: set the Session Instrument to another form, or to none, before removing instrument '${nextSessionInstrumentId}'` + : `The group's Session Instrument must be one of its accessible instruments, and instrument '${nextSessionInstrumentId}' is not` + ); + } + if (nextSessionInstrumentId !== storedSessionInstrumentId) { + const instrument = await this.instrumentsService.findById(nextSessionInstrumentId, options, [groupId]); + if (instrument.kind !== 'FORM') { + throw new BadRequestException(`The group's Session Instrument must be a form, not '${instrument.kind}'`); + } + } + } } diff --git a/apps/api/src/instrument-records/instrument-records.service.ts b/apps/api/src/instrument-records/instrument-records.service.ts index e7170427e..cce91fbb8 100644 --- a/apps/api/src/instrument-records/instrument-records.service.ts +++ b/apps/api/src/instrument-records/instrument-records.service.ts @@ -15,7 +15,7 @@ import { UnprocessableEntityException } from '@nestjs/common'; import { translateInstrument } from '@opendatacapture/instrument-utils'; -import type { Json, ScalarInstrument } from '@opendatacapture/runtime-core'; +import type { FormInstrument, InstrumentValidationSchema, Json, ScalarInstrument } from '@opendatacapture/runtime-core'; import type { CreateInstrumentRecordData, InstrumentRecord, @@ -141,15 +141,7 @@ export class InstrumentRecordsService { await this.subjectsService.findById(subjectId); await this.sessionsService.findById(sessionId); - const parseResult = instrument.validationSchema.safeParse(this.parseJson(rawData)); - if (!parseResult.success) { - throw new UnprocessableEntityException({ - error: 'Unprocessable Entity', - issues: parseResult.error.issues, - message: `Data received for record does not pass validation schema of instrument '${instrument.id}'`, - statusCode: 422 - }); - } + const data = this.parseData(instrument, rawData); return this.instrumentRecordModel.create({ data: { @@ -159,9 +151,9 @@ export class InstrumentRecordsService { } : undefined, computedMeasures: instrument.measures - ? this.instrumentMeasuresService.computeMeasures(instrument.measures, parseResult.data) + ? this.instrumentMeasuresService.computeMeasures(instrument.measures, data) : null, - data: this.serializeData(parseResult.data), + data: this.serializeData(data), date, group: groupId ? { @@ -410,6 +402,26 @@ export class InstrumentRecordsService { return results; } + /** Throws exactly as `create` does for data the instrument's schema rejects. */ + parseData( + instrument: { + id: string; + validationSchema: InstrumentValidationSchema | InstrumentValidationSchema; + }, + rawData: unknown + ) { + const parseResult = instrument.validationSchema.safeParse(this.parseJson(rawData)); + if (!parseResult.success) { + throw new UnprocessableEntityException({ + error: 'Unprocessable Entity', + issues: parseResult.error.issues, + message: `Data received for record does not pass validation schema of instrument '${instrument.id}'`, + statusCode: 422 + }); + } + return parseResult.data; + } + /** * Per-instrument collection statistics for the instrument hub's listing. * diff --git a/apps/api/src/instruments/__tests__/instruments.service.test.ts b/apps/api/src/instruments/__tests__/instruments.service.test.ts index 03cb5f230..d7264f25a 100644 --- a/apps/api/src/instruments/__tests__/instruments.service.test.ts +++ b/apps/api/src/instruments/__tests__/instruments.service.test.ts @@ -728,6 +728,38 @@ describe('InstrumentsService', () => { where: { accessibleInstrumentIds: { has: 'hash:REACTION_TIME-1' } } }); }); + + it('should require a new edition of a form at the start of a session wherever the previous edition was required', async () => { + virtualizationService.eval.mockReturnValue(okAsync(formInstance('INTAKE', 2))); + instrumentModel.exists.mockResolvedValue(false); + + await instrumentsService.create({ bundle: '__BUNDLE__' }); + + expect(groupModel.updateMany).toHaveBeenCalledWith({ + data: { settings: { update: { sessionInstrumentId: 'hash:INTAKE-2' } } }, + where: { settings: { is: { sessionInstrumentId: 'hash:INTAKE-1' } } } + }); + }); + + it('should leave every group on the previous edition when the new one fails to save, so none requires a missing form', async () => { + virtualizationService.eval.mockReturnValue(okAsync(formInstance('INTAKE', 2))); + instrumentModel.exists.mockResolvedValue(false); + instrumentModel.create.mockRejectedValueOnce(new Error('connection reset')); + + await expect(instrumentsService.create({ bundle: '__BUNDLE__' })).rejects.toThrowError('connection reset'); + expect(groupModel.updateMany).not.toHaveBeenCalled(); + }); + + it('should leave a session instrument on its edition when the new edition is not a form, since only a form can be required', async () => { + virtualizationService.eval.mockReturnValue( + okAsync({ ...interactiveInstrument, internal: { edition: 2, name: 'REACTION_TIME' } }) + ); + instrumentModel.exists.mockResolvedValue(false); + + await instrumentsService.create({ bundle: '__BUNDLE__' }); + + expect(groupModel.updateMany).toHaveBeenCalledTimes(1); + }); }); describe('generateSeriesInstrumentId', () => { diff --git a/apps/api/src/instruments/instruments.service.ts b/apps/api/src/instruments/instruments.service.ts index bcc8a42ff..4d84b73de 100644 --- a/apps/api/src/instruments/instruments.service.ts +++ b/apps/api/src/instruments/instruments.service.ts @@ -138,21 +138,6 @@ export class InstrumentsService { if (!result.success) { throw new UnprocessableEntityException(result.message); } - } else if (instance.internal.edition > 1) { - await this.groupModel.updateMany({ - data: { - accessibleInstrumentIds: { - push: [id] - } - }, - where: { - accessibleInstrumentIds: { - has: this.generateScalarInstrumentId({ - internal: { edition: instance.internal.edition - 1, name: instance.internal.name } - }) - } - } - }); } try { @@ -173,6 +158,33 @@ export class InstrumentsService { } throw err; } + + // Only once the edition is stored, so a failed insert leaves no group requiring a missing instrument. + if (instance.kind !== 'SERIES' && instance.internal.edition > 1) { + const previousEditionId = this.generateScalarInstrumentId({ + internal: { edition: instance.internal.edition - 1, name: instance.internal.name } + }); + await this.groupModel.updateMany({ + data: { + accessibleInstrumentIds: { + push: [id] + } + }, + where: { + accessibleInstrumentIds: { + has: previousEditionId + } + } + }); + // A group requiring the previous edition at the start of a session requires this one instead. + // The previous edition stays accessible, so a new edition that is not a form leaves it in place. + if (instance.kind === 'FORM') { + await this.groupModel.updateMany({ + data: { settings: { update: { sessionInstrumentId: id } } }, + where: { settings: { is: { sessionInstrumentId: previousEditionId } } } + }); + } + } return { ...instance, id }; } diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts index ee0d3908b..fd1f4abb3 100644 --- a/apps/api/src/main.ts +++ b/apps/api/src/main.ts @@ -16,6 +16,7 @@ import { MailModule } from './mail/mail.module'; import { PermissionSetsModule } from './permission-sets/permission-sets.module'; import { SessionsModule } from './sessions/sessions.module'; import { SetupModule } from './setup/setup.module'; +import { StartSessionModule } from './start-session/start-session.module'; import { StorageModule } from './storage/storage.module'; import { SubjectsModule } from './subjects/subjects.module'; import { SummaryModule } from './summary/summary.module'; @@ -79,6 +80,7 @@ export default AppFactory.create({ }), SessionsModule, SetupModule, + StartSessionModule, StorageModule, SubjectsModule, SummaryModule, diff --git a/apps/api/src/sessions/__tests__/sessions.controller.test.ts b/apps/api/src/sessions/__tests__/sessions.controller.test.ts index ef9d1fcf1..2a6263b04 100644 --- a/apps/api/src/sessions/__tests__/sessions.controller.test.ts +++ b/apps/api/src/sessions/__tests__/sessions.controller.test.ts @@ -23,19 +23,6 @@ describe('SessionsController', () => { sessionsService = moduleRef.get(SessionsService); }); - it('should create a session with the caller ability, so the group and user are looked up within it', async () => { - const data = { - date: new Date('2024-01-01T00:00:00.000Z'), - groupId: 'group-1', - subjectData: { id: 'subject-1' }, - type: 'IN_PERSON' as const - }; - sessionsService.create.mockResolvedValue({ id: 'session-1' }); - - await expect(sessionsController.create(data, ability)).resolves.toEqual({ id: 'session-1' }); - expect(sessionsService.create).toHaveBeenCalledWith(data, { ability }); - }); - it('should list the requested group sessions within what the caller may read', async () => { const sessions = [{ id: 'session-1' }]; sessionsService.findAllIncludeUsernames.mockResolvedValue(sessions); diff --git a/apps/api/src/sessions/sessions.controller.ts b/apps/api/src/sessions/sessions.controller.ts index e69428ddd..aea55a842 100644 --- a/apps/api/src/sessions/sessions.controller.ts +++ b/apps/api/src/sessions/sessions.controller.ts @@ -1,8 +1,6 @@ import { ApiOperation, CurrentUser } from '@douglasneuroinformatics/libnest'; -import { Body, Controller, Get, Post, Query } from '@nestjs/common'; -import { $CreateSessionData } from '@opendatacapture/schemas/session'; +import { Controller, Get, Query } from '@nestjs/common'; import type { SessionWithUser } from '@opendatacapture/schemas/session'; -import type { Session } from '@prisma/client'; import type { AppAbility } from '@/auth/auth.types'; import { RouteAccess } from '@/core/decorators/route-access.decorator'; @@ -13,13 +11,6 @@ import { SessionsService } from './sessions.service'; export class SessionsController { constructor(private readonly sessionsService: SessionsService) {} - @ApiOperation({ description: 'Create Session' }) - @Post() - @RouteAccess({ action: 'create', subject: 'Session' }) - create(@Body() data: $CreateSessionData, @CurrentUser('ability') ability: AppAbility): Promise { - return this.sessionsService.create(data, { ability }); - } - @ApiOperation({ description: 'Find all sessions and usernames attached to them' }) @Get() @RouteAccess({ action: 'read', subject: 'Session' }) diff --git a/apps/api/src/start-session/__tests__/start-session.controller.test.ts b/apps/api/src/start-session/__tests__/start-session.controller.test.ts new file mode 100644 index 000000000..a33f9f8e4 --- /dev/null +++ b/apps/api/src/start-session/__tests__/start-session.controller.test.ts @@ -0,0 +1,38 @@ +import { MockFactory } from '@douglasneuroinformatics/libnest/testing'; +import type { MockedInstance } from '@douglasneuroinformatics/libnest/testing'; +import { Test } from '@nestjs/testing'; +import { beforeEach, describe, expect, it } from 'vitest'; + +import { createAppAbility } from '@/auth/ability.utils'; + +import { StartSessionController } from '../start-session.controller'; +import { StartSessionService } from '../start-session.service'; + +const ability = createAppAbility([{ action: 'manage', subject: 'Session' }]); + +describe('StartSessionController', () => { + let startSessionController: StartSessionController; + let startSessionService: MockedInstance; + + beforeEach(async () => { + const moduleRef = await Test.createTestingModule({ + controllers: [StartSessionController], + providers: [MockFactory.createForService(StartSessionService)] + }).compile(); + startSessionController = moduleRef.get(StartSessionController); + startSessionService = moduleRef.get(StartSessionService); + }); + + it('should start a session with the caller ability, so the group and user are looked up within it', async () => { + const data = { + date: new Date('2024-01-01T00:00:00.000Z'), + groupId: 'group-1', + subjectData: { id: 'subject-1' }, + type: 'IN_PERSON' as const + }; + startSessionService.start.mockResolvedValue({ id: 'session-1' }); + + await expect(startSessionController.create(data, ability)).resolves.toEqual({ id: 'session-1' }); + expect(startSessionService.start).toHaveBeenCalledWith(data, ability); + }); +}); diff --git a/apps/api/src/start-session/__tests__/start-session.service.test.ts b/apps/api/src/start-session/__tests__/start-session.service.test.ts new file mode 100644 index 000000000..5e5b69a2e --- /dev/null +++ b/apps/api/src/start-session/__tests__/start-session.service.test.ts @@ -0,0 +1,196 @@ +import { MockFactory } from '@douglasneuroinformatics/libnest/testing'; +import type { MockedInstance } from '@douglasneuroinformatics/libnest/testing'; +import { ForbiddenException, UnprocessableEntityException } from '@nestjs/common'; +import { Test } from '@nestjs/testing'; +import type { $StartSessionData } from '@opendatacapture/schemas/session'; +import { beforeEach, describe, expect, it } from 'vitest'; + +import { createAppAbility } from '@/auth/ability.utils'; +import { GroupsService } from '@/groups/groups.service'; +import { InstrumentRecordsService } from '@/instrument-records/instrument-records.service'; +import { InstrumentsService } from '@/instruments/instruments.service'; +import { SessionsService } from '@/sessions/sessions.service'; +import { SubjectsService } from '@/subjects/subjects.service'; + +import { StartSessionService } from '../start-session.service'; + +const ability = createAppAbility([ + { action: 'create', subject: 'Session' }, + { action: 'create', subject: 'InstrumentRecord' } +]); + +const sessionDate = new Date('2026-01-01T09:00:00.000Z'); + +const session = { date: sessionDate, id: 'session-1', subjectId: 'subject-1' }; + +const details: $StartSessionData = { + date: sessionDate, + groupId: 'group-1', + subjectData: { id: 'subject-1' }, + type: 'IN_PERSON' +}; + +const answers = { data: { score: 1 }, instrumentId: 'form-1' }; + +const group = (sessionInstrumentId: null | string) => ({ + id: 'group-1', + name: 'Group One', + settings: { sessionInstrumentId } +}); + +describe('StartSessionService', () => { + let groupsService: MockedInstance; + let instrumentRecordsService: MockedInstance; + let instrumentsService: MockedInstance; + let sessionsService: MockedInstance; + let startSessionService: StartSessionService; + let subjectsService: MockedInstance; + + beforeEach(async () => { + const moduleRef = await Test.createTestingModule({ + providers: [ + StartSessionService, + MockFactory.createForService(GroupsService), + MockFactory.createForService(InstrumentRecordsService), + MockFactory.createForService(InstrumentsService), + MockFactory.createForService(SessionsService), + MockFactory.createForService(SubjectsService) + ] + }).compile(); + groupsService = moduleRef.get(GroupsService); + instrumentRecordsService = moduleRef.get(InstrumentRecordsService); + instrumentsService = moduleRef.get(InstrumentsService); + sessionsService = moduleRef.get(SessionsService); + startSessionService = moduleRef.get(StartSessionService); + subjectsService = moduleRef.get(SubjectsService); + sessionsService.create.mockResolvedValue(session); + instrumentsService.findById.mockResolvedValue({ id: 'form-1', kind: 'FORM' }); + }); + + describe('in a group requiring no session instrument', () => { + beforeEach(() => { + groupsService.findById.mockResolvedValue(group(null)); + }); + + it("should create the session within the caller's ability", async () => { + await expect(startSessionService.start(details, ability)).resolves.toBe(session); + expect(groupsService.findById).toHaveBeenCalledWith('group-1', { ability }); + expect(sessionsService.create).toHaveBeenCalledWith(details, { ability }); + }); + + it('should refuse answers to a session instrument rather than drop them, so a misconfigured client is noticed', async () => { + await expect( + startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability) + ).rejects.toThrow(UnprocessableEntityException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + }); + + describe('outside any group', () => { + it('should create the session without looking up a group', async () => { + await startSessionService.start({ ...details, groupId: null }, ability); + expect(groupsService.findById).not.toHaveBeenCalled(); + expect(sessionsService.create).toHaveBeenCalledWith({ ...details, groupId: null }, { ability }); + }); + + it('should refuse answers to a session instrument, since no group requires one', async () => { + await expect( + startSessionService.start({ ...details, groupId: null, sessionInstrumentAnswers: answers }, ability) + ).rejects.toThrow(UnprocessableEntityException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + }); + + describe('in a group requiring a session instrument', () => { + beforeEach(() => { + groupsService.findById.mockResolvedValue(group('form-1')); + }); + + it('should refuse to start a session without the answers', async () => { + await expect(startSessionService.start(details, ability)).rejects.toThrow(UnprocessableEntityException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + + it('should refuse answers to any instrument but the one the group requires', async () => { + await expect( + startSessionService.start( + { ...details, sessionInstrumentAnswers: { ...answers, instrumentId: 'form-2' } }, + ability + ) + ).rejects.toThrow(UnprocessableEntityException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + + it('should refuse a caller who may not create records, since the session would bring one with it', async () => { + const sessionOnly = createAppAbility([{ action: 'create', subject: 'Session' }]); + await expect( + startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, sessionOnly) + ).rejects.toThrow(ForbiddenException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + + it('should refuse a session instrument that is not a form', async () => { + instrumentsService.findById.mockResolvedValueOnce({ id: 'form-1', kind: 'INTERACTIVE' }); + await expect( + startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability) + ).rejects.toThrow(UnprocessableEntityException); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + + it('should refuse answers the instrument rejects before creating anything, so no subject is left behind', async () => { + const rejection = new UnprocessableEntityException('invalid'); + instrumentRecordsService.parseData.mockImplementationOnce(() => { + throw rejection; + }); + await expect(startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability)).rejects.toBe( + rejection + ); + expect(sessionsService.create).not.toHaveBeenCalled(); + }); + + it("should look the instrument up within the caller's ability and the session's group", async () => { + await startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability); + expect(instrumentsService.findById).toHaveBeenCalledWith('form-1', { ability }, ['group-1']); + }); + + it('should create the record of the answers in the new session, dated as the session is', async () => { + await expect(startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability)).resolves.toBe( + session + ); + expect(sessionsService.create).toHaveBeenCalledWith(details, { ability }); + expect(instrumentRecordsService.create).toHaveBeenCalledWith( + { + data: answers.data, + date: sessionDate, + groupId: 'group-1', + instrumentId: 'form-1', + sessionId: 'session-1', + subjectId: 'subject-1' + }, + { ability } + ); + }); + + it('should delete the session and the subject it created when its record cannot be created, so none is kept', async () => { + const failure = new Error('write failed'); + subjectsService.exists.mockResolvedValueOnce(false); + instrumentRecordsService.create.mockRejectedValueOnce(failure); + await expect(startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability)).rejects.toBe( + failure + ); + expect(sessionsService.deleteById).toHaveBeenCalledWith('session-1'); + expect(subjectsService.deleteById).toHaveBeenCalledWith('subject-1'); + }); + + it('should keep a subject that existed before the session when its record cannot be created', async () => { + const failure = new Error('write failed'); + subjectsService.exists.mockResolvedValueOnce(true); + instrumentRecordsService.create.mockRejectedValueOnce(failure); + await expect(startSessionService.start({ ...details, sessionInstrumentAnswers: answers }, ability)).rejects.toBe( + failure + ); + expect(sessionsService.deleteById).toHaveBeenCalledWith('session-1'); + expect(subjectsService.deleteById).not.toHaveBeenCalled(); + }); + }); +}); diff --git a/apps/api/src/start-session/start-session.controller.ts b/apps/api/src/start-session/start-session.controller.ts new file mode 100644 index 000000000..e74a7e3d8 --- /dev/null +++ b/apps/api/src/start-session/start-session.controller.ts @@ -0,0 +1,25 @@ +import { ApiOperation, CurrentUser } from '@douglasneuroinformatics/libnest'; +import { Body, Controller, Post } from '@nestjs/common'; +import { $StartSessionData } from '@opendatacapture/schemas/session'; +import type { Session } from '@prisma/client'; + +import type { AppAbility } from '@/auth/auth.types'; +import { RouteAccess } from '@/core/decorators/route-access.decorator'; + +import { StartSessionService } from './start-session.service'; + +@Controller('sessions') +export class StartSessionController { + constructor(private readonly startSessionService: StartSessionService) {} + + @ApiOperation({ + description: + "Create a session. When the session's group requires a session instrument, the answers to it are created as a record of the session in the same request, or neither is created.", + summary: 'Create Session' + }) + @Post() + @RouteAccess({ action: 'create', subject: 'Session' }) + create(@Body() data: $StartSessionData, @CurrentUser('ability') ability: AppAbility): Promise { + return this.startSessionService.start(data, ability); + } +} diff --git a/apps/api/src/start-session/start-session.module.ts b/apps/api/src/start-session/start-session.module.ts new file mode 100644 index 000000000..38f0a2e95 --- /dev/null +++ b/apps/api/src/start-session/start-session.module.ts @@ -0,0 +1,19 @@ +import { Module } from '@nestjs/common'; + +import { GroupsModule } from '@/groups/groups.module'; +import { InstrumentRecordsModule } from '@/instrument-records/instrument-records.module'; +import { InstrumentsModule } from '@/instruments/instruments.module'; +import { SessionsModule } from '@/sessions/sessions.module'; +import { SubjectsModule } from '@/subjects/subjects.module'; + +import { StartSessionController } from './start-session.controller'; +import { StartSessionService } from './start-session.service'; + +// Starting a session creates the record of the group's session instrument with it, and +// `InstrumentRecordsModule` already imports `SessionsModule`, so the two meet here rather than in either. +@Module({ + controllers: [StartSessionController], + imports: [GroupsModule, InstrumentRecordsModule, InstrumentsModule, SessionsModule, SubjectsModule], + providers: [StartSessionService] +}) +export class StartSessionModule {} diff --git a/apps/api/src/start-session/start-session.service.ts b/apps/api/src/start-session/start-session.service.ts new file mode 100644 index 000000000..18a1eab3e --- /dev/null +++ b/apps/api/src/start-session/start-session.service.ts @@ -0,0 +1,81 @@ +import { ForbiddenException, Injectable, UnprocessableEntityException } from '@nestjs/common'; +import type { $StartSessionData } from '@opendatacapture/schemas/session'; +import type { Session } from '@prisma/client'; + +import type { AppAbility } from '@/auth/auth.types'; +import { GroupsService } from '@/groups/groups.service'; +import { InstrumentRecordsService } from '@/instrument-records/instrument-records.service'; +import { InstrumentsService } from '@/instruments/instruments.service'; +import { SessionsService } from '@/sessions/sessions.service'; +import { SubjectsService } from '@/subjects/subjects.service'; + +/** + * A session started over HTTP, which is where a group's session instrument is required. The gateway + * synchronizer, CSV upload and the demo seeder create sessions through `SessionsService` directly, so + * none of them is asked for one. + */ +@Injectable() +export class StartSessionService { + constructor( + private readonly groupsService: GroupsService, + private readonly instrumentRecordsService: InstrumentRecordsService, + private readonly instrumentsService: InstrumentsService, + private readonly sessionsService: SessionsService, + private readonly subjectsService: SubjectsService + ) {} + + async start({ sessionInstrumentAnswers, ...data }: $StartSessionData, ability: AppAbility): Promise { + const group = data.groupId ? await this.groupsService.findById(data.groupId, { ability }) : null; + const sessionInstrumentId = group?.settings.sessionInstrumentId; + if (!group || !sessionInstrumentId) { + if (sessionInstrumentAnswers) { + throw new UnprocessableEntityException( + "Answers to a session instrument were sent, but the session's group requires no session instrument" + ); + } + return this.sessionsService.create(data, { ability }); + } + if (sessionInstrumentAnswers?.instrumentId !== sessionInstrumentId) { + throw new UnprocessableEntityException( + `Group '${group.name}' requires its session instrument '${sessionInstrumentId}' to be completed to start a session` + ); + } + if (!ability.can('create', 'InstrumentRecord')) { + throw new ForbiddenException( + `Starting a session in group '${group.name}' creates a record of its session instrument, which requires permission to create instrument records` + ); + } + + // Refused before anything is written, so answers the instrument rejects create no subject either. + const instrument = await this.instrumentsService.findById(sessionInstrumentId, { ability }, [group.id]); + if (instrument.kind !== 'FORM') { + throw new UnprocessableEntityException(`Session instrument '${sessionInstrumentId}' is not a form`); + } + this.instrumentRecordsService.parseData(instrument, sessionInstrumentAnswers.data); + + const isNewSubject = !(await this.subjectsService.exists(data.subjectData.id)); + const session = await this.sessionsService.create(data, { ability }); + try { + await this.instrumentRecordsService.create( + { + data: sessionInstrumentAnswers.data, + date: session.date, + groupId: group.id, + instrumentId: sessionInstrumentId, + sessionId: session.id, + subjectId: session.subjectId + }, + { ability } + ); + } catch (err) { + // Unscoped, as `SessionsService.createMany` rolls back: the caller may create sessions and + // subjects without being allowed to delete them, and these were created by this request a moment ago. + await this.sessionsService.deleteById(session.id); + if (isNewSubject) { + await this.subjectsService.deleteById(session.subjectId); + } + throw err; + } + return session; + } +} diff --git a/apps/api/src/subjects/__tests__/subjects.service.test.ts b/apps/api/src/subjects/__tests__/subjects.service.test.ts index 15f2c5b88..c0a9a5a1c 100644 --- a/apps/api/src/subjects/__tests__/subjects.service.test.ts +++ b/apps/api/src/subjects/__tests__/subjects.service.test.ts @@ -192,6 +192,14 @@ describe('SubjectsService', () => { }); }); + describe('exists', () => { + it('should look the id up in every group, so a subject the caller cannot read still counts', async () => { + subjectModel.exists.mockResolvedValueOnce(true); + await expect(subjectsService.exists('subject-1')).resolves.toBe(true); + expect(subjectModel.exists).toHaveBeenCalledWith({ id: 'subject-1' }); + }); + }); + describe('find', () => { it('should return the array returned by the subject model', async () => { subjectModel.findMany.mockResolvedValueOnce([{ id: '123' }]); diff --git a/apps/api/src/subjects/subjects.service.ts b/apps/api/src/subjects/subjects.service.ts index 382e64d1d..8a722accd 100644 --- a/apps/api/src/subjects/subjects.service.ts +++ b/apps/api/src/subjects/subjects.service.ts @@ -170,6 +170,14 @@ export class SubjectsService { return { success: true }; } + /** + * Unscoped, because a subject in a group the caller cannot read is still the subject with this id, + * and only whether it exists leaves the service. + */ + async exists(id: string): Promise { + return this.subjectModel.exists({ id }); + } + async find( { groupId, hasRecord }: { groupId?: string; hasRecord?: boolean } = {}, { ability }: EntityOperationOptions = {} diff --git a/apps/api/test/helpers.ts b/apps/api/test/helpers.ts index 590dab547..f891ec391 100644 --- a/apps/api/test/helpers.ts +++ b/apps/api/test/helpers.ts @@ -62,17 +62,20 @@ export function defineSuite(name: string, fn: (this: TestSuiteThis) => Promise { const { z } = await import(${JSON.stringify(import.meta.resolve('zod/v4'))}); return { __runtimeVersion: 1, content: { score: { kind: 'number', label: 'Score', variant: 'input' } }, details: { description: 'A form with one number field', license: 'Apache-2.0', title: ${JSON.stringify(name)} }, - internal: { edition: 1, name: ${JSON.stringify(name)} }, + internal: { edition: ${edition}, name: ${JSON.stringify(name)} }, kind: 'FORM', language: 'en', measures: ${measured ? "{ score: { kind: 'const', label: 'Score', ref: 'score' } }" : 'null'}, diff --git a/apps/api/test/suites/10-session-instrument.suite.ts b/apps/api/test/suites/10-session-instrument.suite.ts new file mode 100644 index 000000000..a72943cf7 --- /dev/null +++ b/apps/api/test/suites/10-session-instrument.suite.ts @@ -0,0 +1,153 @@ +import { randomUUID } from 'node:crypto'; + +import { beforeAll, describe, expect, it } from 'vitest'; + +import { InstrumentsService } from '@/instruments/instruments.service'; + +import { defineSuite, scoreFormBundle } from '../helpers'; + +type Group = { accessibleInstrumentIds: string[]; id: string; settings: { sessionInstrumentId?: null | string } }; + +export default defineSuite('session instrument', function () { + let adminHeaders: { authorization: string }; + let otherFormId: string; + let sessionInstrumentId: string; + + const createGroup = async (settings?: { [key: string]: unknown }) => { + const response = await this.app.inject({ + headers: adminHeaders, + method: 'POST', + payload: { name: `Session Instrument ${randomUUID()}`, settings, type: 'RESEARCH' }, + url: '/v1/groups' + }); + expect(response.statusCode).toBe(201); + return response.json(); + }; + + const updateGroup = (groupId: string, payload: { [key: string]: unknown }) => { + return this.app.inject({ headers: adminHeaders, method: 'PATCH', payload, url: `/v1/groups/${groupId}` }); + }; + + const groupRequiringSessionInstrument = async () => { + const group = await createGroup(); + const response = await updateGroup(group.id, { + accessibleInstrumentIds: [sessionInstrumentId, otherFormId], + settings: { sessionInstrumentId } + }); + expect(response.statusCode).toBe(200); + return response.json(); + }; + + const startSession = (groupId: string, extra: { [key: string]: unknown } = {}) => { + const subjectId = `session-instrument-${randomUUID()}`; + const request = this.app.inject({ + headers: adminHeaders, + method: 'POST', + payload: { + date: '2026-03-04T05:06:07.000Z', + groupId, + subjectData: { id: subjectId }, + type: 'RETROSPECTIVE', + ...extra + }, + url: '/v1/sessions' + }); + return { request, subjectId }; + }; + + const subjectExists = async (subjectId: string) => { + const response = await this.app.inject({ headers: adminHeaders, method: 'GET', url: `/v1/subjects/${subjectId}` }); + return response.statusCode === 200; + }; + + beforeAll(async () => { + const login = await this.app.inject({ + method: 'POST', + payload: { password: 'DataCapture2025_Test', username: 'admin' }, + url: '/v1/auth/login' + }); + expect(login.statusCode).toBe(200); + adminHeaders = { authorization: `Bearer ${login.json<{ accessToken: string }>().accessToken}` }; + const instruments = this.app.get(InstrumentsService); + sessionInstrumentId = (await instruments.create({ bundle: scoreFormBundle('SESSION_INSTRUMENT') })).id; + otherFormId = (await instruments.create({ bundle: scoreFormBundle('SESSION_INSTRUMENT_OTHER') })).id; + }); + + describe('POST /v1/sessions', () => { + it('should create the session and a record of the answers in it, dated as the session is', async () => { + const group = await groupRequiringSessionInstrument(); + const { request, subjectId } = startSession(group.id, { + sessionInstrumentAnswers: { data: { score: 7 }, instrumentId: sessionInstrumentId } + }); + const response = await request; + expect(response.statusCode).toBe(201); + const session = response.json<{ id: string }>(); + + const records = await this.app.inject({ + headers: adminHeaders, + method: 'GET', + url: `/v1/instrument-records?subjectId=${subjectId}` + }); + expect(records.json()).toMatchObject([ + { + data: { score: 7 }, + date: '2026-03-04T05:06:07.000Z', + instrumentId: sessionInstrumentId, + sessionId: session.id + } + ]); + }); + + it('should refuse a session without the answers, creating neither it nor its subject', async () => { + const group = await groupRequiringSessionInstrument(); + const { request, subjectId } = startSession(group.id); + expect((await request).statusCode).toBe(422); + expect(await subjectExists(subjectId)).toBe(false); + }); + + it('should refuse answers the instrument rejects, creating neither the session nor its subject', async () => { + const group = await groupRequiringSessionInstrument(); + const { request, subjectId } = startSession(group.id, { + sessionInstrumentAnswers: { data: { score: 'seven' }, instrumentId: sessionInstrumentId } + }); + expect((await request).statusCode).toBe(422); + expect(await subjectExists(subjectId)).toBe(false); + }); + + it('should refuse answers sent for a group that requires none, rather than drop them', async () => { + const group = await createGroup(); + const { request } = startSession(group.id, { + sessionInstrumentAnswers: { data: { score: 7 }, instrumentId: sessionInstrumentId } + }); + expect((await request).statusCode).toBe(422); + }); + }); + + describe('PATCH /v1/groups/:id', () => { + it("should refuse to remove the session instrument from the group's instruments, naming the setting", async () => { + const group = await groupRequiringSessionInstrument(); + const response = await updateGroup(group.id, { accessibleInstrumentIds: [otherFormId] }); + expect(response.statusCode).toBe(400); + expect(response.json<{ message: string }>().message).toContain('Session Instrument'); + }); + }); + + describe('POST /v1/groups', () => { + it('should create a group without a session instrument, even when one is sent', async () => { + const group = await createGroup({ defaultIdentificationMethod: 'CUSTOM_ID', sessionInstrumentId }); + expect(group.settings.sessionInstrumentId).toBeFalsy(); + }); + }); + + describe('a new edition of the session instrument', () => { + it('should become the session instrument of every group that required the previous edition', async () => { + const group = await groupRequiringSessionInstrument(); + const nextEdition = await this.app + .get(InstrumentsService) + .create({ bundle: scoreFormBundle('SESSION_INSTRUMENT', { edition: 2 }) }); + + const response = await this.app.inject({ headers: adminHeaders, method: 'GET', url: `/v1/groups/${group.id}` }); + expect(response.json().settings.sessionInstrumentId).toBe(nextEdition.id); + }); + }); +}); diff --git a/apps/web/src/components/SessionInstrumentStep/SessionInstrumentStep.tsx b/apps/web/src/components/SessionInstrumentStep/SessionInstrumentStep.tsx new file mode 100644 index 000000000..1dd71dd63 --- /dev/null +++ b/apps/web/src/components/SessionInstrumentStep/SessionInstrumentStep.tsx @@ -0,0 +1,40 @@ +import { Button, Spinner } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import { InstrumentRenderer } from '@opendatacapture/react-core'; +import type { InstrumentSubmitHandler } from '@opendatacapture/react-core'; +import { ArrowLeftIcon } from 'lucide-react'; + +import { NavigationBlocker } from '@/components/NavigationBlocker'; +import { useInstrumentBundle } from '@/hooks/useInstrumentBundle'; + +type SessionInstrumentStepProps = { + instrumentId: string; + onBack: () => void; + onSubmit: InstrumentSubmitHandler; +}; + +export const SessionInstrumentStep = ({ instrumentId, onBack, onSubmit }: SessionInstrumentStepProps) => { + const { t } = useTranslation(); + const instrumentBundleQuery = useInstrumentBundle(instrumentId); + + return ( +
+
+ +
+ {instrumentBundleQuery.data ? ( + + ) : ( + + )} +
+ ); +}; diff --git a/apps/web/src/components/SessionInstrumentStep/__tests__/SessionInstrumentStep.test.tsx b/apps/web/src/components/SessionInstrumentStep/__tests__/SessionInstrumentStep.test.tsx new file mode 100644 index 000000000..5ab6b4f91 --- /dev/null +++ b/apps/web/src/components/SessionInstrumentStep/__tests__/SessionInstrumentStep.test.tsx @@ -0,0 +1,58 @@ +import type { InstrumentRendererProps } from '@opendatacapture/react-core'; +import { cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { SessionInstrumentStep } from '../SessionInstrumentStep'; + +import '@/services/i18n'; + +const mocks = vi.hoisted(() => ({ + bundle: undefined as undefined | { bundle: string; id: string; kind: 'FORM' }, + InstrumentRenderer: vi.fn((_props: InstrumentRendererProps) =>
), + useInstrumentBundle: vi.fn() +})); + +vi.mock('@opendatacapture/react-core', () => ({ InstrumentRenderer: mocks.InstrumentRenderer })); +vi.mock('@/hooks/useInstrumentBundle', () => ({ + useInstrumentBundle: (id: string) => { + mocks.useInstrumentBundle(id); + return { data: mocks.bundle }; + } +})); +vi.mock('@/components/NavigationBlocker', () => ({ NavigationBlocker: () => null })); + +describe('SessionInstrumentStep', () => { + afterEach(() => { + cleanup(); + vi.clearAllMocks(); + mocks.bundle = undefined; + }); + + it('should load the bundle of the session instrument', () => { + render(); + expect(mocks.useInstrumentBundle).toHaveBeenCalledWith('form-1'); + }); + + it('should wait for the bundle before rendering the instrument', () => { + render(); + expect(screen.queryByTestId('instrument-renderer')).toBeNull(); + }); + + it('should render the instrument, submitting its answers to the page and blocking navigation away from them', () => { + mocks.bundle = { bundle: '__BUNDLE__', id: 'form-1', kind: 'FORM' }; + const onSubmit = vi.fn(); + render(); + expect(mocks.InstrumentRenderer.mock.lastCall?.[0]).toMatchObject({ + NavigationBlocker: expect.any(Function), + onSubmit, + target: mocks.bundle + }); + }); + + it('should return to the session details when the clinician goes back', () => { + const onBack = vi.fn(); + render(); + fireEvent.click(screen.getByTestId('session-instrument-back')); + expect(onBack).toHaveBeenCalledOnce(); + }); +}); diff --git a/apps/web/src/components/SessionInstrumentStep/index.ts b/apps/web/src/components/SessionInstrumentStep/index.ts new file mode 100644 index 000000000..adf37fd56 --- /dev/null +++ b/apps/web/src/components/SessionInstrumentStep/index.ts @@ -0,0 +1 @@ +export * from './SessionInstrumentStep'; diff --git a/apps/web/src/hooks/__tests__/useUpdateGroupMutation.test.ts b/apps/web/src/hooks/__tests__/useUpdateGroupMutation.test.ts index 0fde8f732..2966f60eb 100644 --- a/apps/web/src/hooks/__tests__/useUpdateGroupMutation.test.ts +++ b/apps/web/src/hooks/__tests__/useUpdateGroupMutation.test.ts @@ -39,7 +39,7 @@ function renderUpdateMutation(options?: Parameters { return createElement(QueryClientProvider, { children, client: queryClient }); }; - return renderHook(() => useUpdateGroupMutation(options), { wrapper }); + return { ...renderHook(() => useUpdateGroupMutation(options), { wrapper }), queryClient }; } describe('useUpdateGroupMutation', () => { @@ -49,6 +49,12 @@ describe('useUpdateGroupMutation', () => { store.currentGroup = { id: 'group-1' }; }); + it('should seed the group query with the saved group, so a page reading it fresh shows the save', async () => { + const { queryClient, result } = renderUpdateMutation(); + await result.current.mutateAsync({ name: 'Renamed' }); + expect(queryClient.getQueryData(['group', 'group-1'])).toMatchObject({ id: 'group-1', name: 'Group One' }); + }); + it('patches the currently selected group and keeps the default error toast', async () => { const { result } = renderUpdateMutation(); await result.current.mutateAsync({ name: 'Renamed' }); diff --git a/apps/web/src/hooks/useCreateSessionMutation.ts b/apps/web/src/hooks/useCreateSessionMutation.ts index e53bb8fbd..69e220e23 100644 --- a/apps/web/src/hooks/useCreateSessionMutation.ts +++ b/apps/web/src/hooks/useCreateSessionMutation.ts @@ -1,13 +1,13 @@ import { useNotificationsStore } from '@douglasneuroinformatics/libui/hooks'; import { $Session } from '@opendatacapture/schemas/session'; -import type { $CreateSessionData } from '@opendatacapture/schemas/session'; +import type { $StartSessionData } from '@opendatacapture/schemas/session'; import { useMutation } from '@tanstack/react-query'; import axios from 'axios'; export function useCreateSessionMutation() { const addNotification = useNotificationsStore((store) => store.addNotification); return useMutation({ - mutationFn: async (data: $CreateSessionData) => { + mutationFn: async (data: $StartSessionData) => { const response = await axios.post('/v1/sessions', data); return $Session.parseAsync(response.data); }, diff --git a/apps/web/src/hooks/useUpdateGroupMutation.ts b/apps/web/src/hooks/useUpdateGroupMutation.ts index cdb08274b..6aa048e53 100644 --- a/apps/web/src/hooks/useUpdateGroupMutation.ts +++ b/apps/web/src/hooks/useUpdateGroupMutation.ts @@ -1,11 +1,13 @@ import { useNotificationsStore } from '@douglasneuroinformatics/libui/hooks'; import { $Group } from '@opendatacapture/schemas/group'; import type { $UpdateGroupData } from '@opendatacapture/schemas/group'; -import { useMutation } from '@tanstack/react-query'; +import { useMutation, useQueryClient } from '@tanstack/react-query'; import axios from 'axios'; import { useAppStore } from '@/store'; +import { groupQueryOptions } from './useGroupQuery'; + type UpdateGroupMutationOptions = { /** Whether a success toast is raised. Opt out where the caller renders its own save feedback. */ successNotification?: boolean; @@ -22,6 +24,7 @@ export function useUpdateGroupMutation({ }: UpdateGroupMutationOptions = {}) { const addNotification = useNotificationsStore((store) => store.addNotification); const currentGroup = useAppStore((store) => store.currentGroup); + const queryClient = useQueryClient(); return useMutation({ mutationFn: async (data: $UpdateGroupData) => { // A caller that opts out of throwing is declaring it renders its own failure feedback, so @@ -31,7 +34,9 @@ export function useUpdateGroupMutation({ }); return $Group.parseAsync(response.data); }, - onSuccess() { + onSuccess(group) { + // Pages that read the group fresh rather than from the store must see what was just saved. + queryClient.setQueryData(groupQueryOptions(group.id).queryKey, group); if (successNotification) { addNotification({ type: 'success' }); } diff --git a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx index 98d295254..9e7650eee 100644 --- a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx +++ b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx @@ -12,16 +12,26 @@ import '@/services/i18n'; type DeleteCallbacks = { onSettled: () => void; onSuccess: () => void }; +type Loader = (ctx: { + context: { queryClient: { fetchQuery: (options: object) => Promise } }; +}) => Promise; + const mocks = vi.hoisted(() => ({ changeGroup: vi.fn(), createMutateAsync: vi.fn(), deleteMutate: vi.fn(), + /** The group as `GET /v1/groups/:id` returns it; the store's copy dates from sign-in. */ + fetchedGroup: undefined as Group | undefined, instruments: undefined as TranslatedInstrumentInfo[] | undefined, isDemo: false, store: { currentGroup: null as Group | null }, updateMutateAsync: vi.fn<(data: Partial<$UpdateGroupData>) => Promise>() })); +vi.mock('@/hooks/useGroupQuery', async (importOriginal) => ({ + ...(await importOriginal()), + useGroupQuery: (groupId: null | string | undefined) => ({ data: groupId ? mocks.fetchedGroup : undefined }) +})); vi.mock('@/hooks/useInstrumentInfoQuery', () => ({ useInstrumentInfoQuery: () => ({ data: mocks.instruments }) })); @@ -38,11 +48,12 @@ vi.mock('@/hooks/useUpdateGroupMutation', () => ({ useUpdateGroupMutation: () => ({ mutateAsync: mocks.updateMutateAsync }) })); vi.mock('@/store', () => ({ - useAppStore: ( - selector: (store: { changeGroup: typeof mocks.changeGroup; currentGroup: Group | null }) => unknown - ) => { - return selector({ changeGroup: mocks.changeGroup, currentGroup: mocks.store.currentGroup }); - } + useAppStore: Object.assign( + (selector: (store: { changeGroup: typeof mocks.changeGroup; currentGroup: Group | null }) => unknown) => { + return selector({ changeGroup: mocks.changeGroup, currentGroup: mocks.store.currentGroup }); + }, + { getState: () => ({ currentGroup: mocks.store.currentGroup }) } + ) })); vi.mock('@/components/LoadingFallback', () => ({ LoadingFallback: () =>
@@ -65,14 +76,18 @@ vi.mock('@/components/InstrumentPreviewDialog', () => ({ const scalar = ({ createdAt = null, + edition = 1, id, kind = 'FORM', + name = id, sourceRepo = null, title }: { createdAt?: Date | null; + edition?: number; id: string; kind?: 'FILE' | 'FORM' | 'INTERACTIVE'; + name?: string; sourceRepo?: null | { id: string; name: null | string }; title: string; }): TranslatedInstrumentInfo => ({ @@ -80,7 +95,7 @@ const scalar = ({ createdAt, details: { authors: null, description: `${title} description`, license: 'MIT', title }, id, - internal: { edition: 1, name: id }, + internal: { edition, name }, kind, language: 'en', sourceRepo, @@ -139,7 +154,13 @@ const defaultInstruments = () => [ const RouteComponent = Route.options.component!; -const renderPage = () => render(); +const loader = Route.options.loader as Loader; + +/** Renders with the server holding the same group as the store, unless a test says otherwise. */ +const renderPage = () => { + mocks.fetchedGroup ??= mocks.store.currentGroup ?? undefined; + return render(); +}; const rerenderPage = (rerender: (ui: ReactNode) => void) => rerender(); @@ -175,6 +196,7 @@ const resolveCreate = (result: CreateSeriesInstrumentResult) => mocks.createMuta describe('Route', () => { beforeEach(() => { vi.clearAllMocks(); + mocks.fetchedGroup = undefined; mocks.instruments = defaultInstruments(); mocks.isDemo = false; mocks.store.currentGroup = makeGroup(); @@ -198,6 +220,13 @@ describe('Route', () => { expect(screen.queryByText('Accessible Instruments')).toBeNull(); }); + it('should show a loading fallback until the group has been read from the server', () => { + mocks.fetchedGroup = undefined; + render(); + expect(screen.getByTestId('loading-fallback')).toBeTruthy(); + expect(screen.queryByText('Accessible Instruments')).toBeNull(); + }); + it('should show a loading fallback when no group is selected, since there is nothing to manage', () => { mocks.store.currentGroup = null; renderPage(); @@ -640,6 +669,7 @@ describe('Route', () => { idValidationRegex: '^[0-9]+$', idValidationRegexErrorMessage: { en: 'Digits only', fr: 'Chiffres seulement' }, minimumAge: 18, + sessionInstrumentId: null, subjectIdDisplayLength: 6 } }) @@ -677,4 +707,94 @@ describe('Route', () => { expect(screen.queryByText('Custom ID Validation Message (English)')).toBeNull(); }); }); + + describe('session instrument', () => { + const requiring = (sessionInstrumentId: string) => { + return makeGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_ID', sessionInstrumentId } }); + }; + + const sessionInstrumentOptions = () => { + const select = document.querySelector('select[name="sessionInstrumentId"]')!; + return Array.from(select.options, (option) => option.textContent).filter(Boolean); + }; + + const savedSessionInstrumentId = () => mocks.updateMutateAsync.mock.lastCall?.[0].settings?.sessionInstrumentId; + + it('should save no session instrument for a group that requires none', async () => { + renderPage(); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(savedSessionInstrumentId()).toBeNull(); + }); + + it('should keep the session instrument the group requires', async () => { + mocks.store.currentGroup = requiring('form-1'); + renderPage(); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(savedSessionInstrumentId()).toBe('form-1'); + }); + + it('should offer only the forms the group has selected, since only those can be required', () => { + renderPage(); + expect(sessionInstrumentOptions()).toEqual(['None', 'Happiness Questionnaire']); + fireEvent.click(checkbox('Breakfast Survey')); + expect(sessionInstrumentOptions()).toEqual(['None', 'Happiness Questionnaire', 'Breakfast Survey']); + }); + + it('should tell two forms with the same title apart by their names', () => { + mocks.instruments = [ + ...defaultInstruments(), + scalar({ id: 'form-3', name: 'HAPPINESS_SHORT', title: 'Happiness Questionnaire' }) + ]; + mocks.store.currentGroup = makeGroup({ accessibleInstrumentIds: ['form-1', 'form-3'] }); + renderPage(); + expect(sessionInstrumentOptions()).toEqual([ + 'None', + 'Happiness Questionnaire (form-1)', + 'Happiness Questionnaire (HAPPINESS_SHORT)' + ]); + }); + + it('should seed the setting from the group the server holds, so a save cannot undo a change made since sign-in', async () => { + mocks.store.currentGroup = makeGroup(); + mocks.fetchedGroup = requiring('form-1'); + renderPage(); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(savedSessionInstrumentId()).toBe('form-1'); + }); + + it('should refuse to save once the session instrument is no longer selected, rather than lose the group access to it', async () => { + mocks.store.currentGroup = requiring('form-1'); + renderPage(); + fireEvent.click(checkbox('Happiness Questionnaire')); + submitSettings(); + expect(await screen.findByText(/The session instrument must be one of the group's instruments/)).toBeTruthy(); + expect(mocks.updateMutateAsync).not.toHaveBeenCalled(); + }); + + it('should accept a session instrument the list does not display but the group can still access', async () => { + mocks.store.currentGroup = requiring('missing-1'); + renderPage(); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(savedSessionInstrumentId()).toBe('missing-1'); + }); + }); + + describe('loader', () => { + it('should fetch the current group even when it is cached, since the form saves every setting it is seeded with', async () => { + const fetchQuery = vi.fn(() => Promise.resolve()); + await loader({ context: { queryClient: { fetchQuery } } }); + expect(fetchQuery).toHaveBeenCalledWith(expect.objectContaining({ queryKey: ['group', 'group-1'] })); + }); + + it('should fetch nothing when no group is selected', async () => { + mocks.store.currentGroup = null; + const fetchQuery = vi.fn(() => Promise.resolve()); + await loader({ context: { queryClient: { fetchQuery } } }); + expect(fetchQuery).not.toHaveBeenCalled(); + }); + }); }); diff --git a/apps/web/src/routes/_app/group/manage.tsx b/apps/web/src/routes/_app/group/manage.tsx index e5cc5c3e3..a463472d6 100644 --- a/apps/web/src/routes/_app/group/manage.tsx +++ b/apps/web/src/routes/_app/group/manage.tsx @@ -30,6 +30,7 @@ import { PageHeader } from '@/components/PageHeader'; import { WithFallback } from '@/components/WithFallback'; import { useCreateSeriesInstrumentMutation } from '@/hooks/useCreateSeriesInstrumentMutation'; import { useDeleteSeriesInstrumentMutation } from '@/hooks/useDeleteSeriesInstrumentMutation'; +import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { useInstrumentInfoQuery } from '@/hooks/useInstrumentInfoQuery'; import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; import { useUpdateGroupMutation } from '@/hooks/useUpdateGroupMutation'; @@ -80,6 +81,9 @@ const expandSelectedSeriesIds = ({ return expandedIds; }; +/** The select's value for a group requiring no session instrument; instrument ids are hashes, so none is this. */ +const NO_SESSION_INSTRUMENT = 'NONE'; + type SettingsValues = { defaultIdentificationMethod?: SubjectIdentificationMethod; idValidationRegex?: null | string; @@ -87,6 +91,7 @@ type SettingsValues = { idValidationRegexErrorMessageFr?: null | string; minimumAge?: null | number; minimumAgeApplied?: boolean | null; + sessionInstrumentId?: string; subjectIdDisplayLength?: null | number; }; @@ -594,6 +599,17 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => [instruments] ); + // Only a form the group will be able to access may be required, so the options follow the selection. + // The list holds the latest edition of each form, so a shared title is two forms, told apart by name. + const selectedForms = instruments.form.filter((item) => selectedIds.has(item.id)); + const sessionInstrumentOptions = Object.fromEntries( + selectedForms.map((item) => { + const isTitleShared = selectedForms.some((other) => other !== item && other.title === item.title); + const label = isTitleShared && item.internal ? `${item.title} (${item.internal.name})` : item.title; + return [item.id, label]; + }) + ); + return (
{previewItem && ( @@ -795,6 +811,25 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => } }, title: t('group.manage.groupSettings') + }, + { + fields: { + sessionInstrumentId: { + description: t({ + en: 'A form completed as part of starting every session in this group. The session is created only once the form is submitted.', + es: 'Un formulario que se completa al iniciar cada sesión en este grupo. La sesión se crea solo cuando se envía el formulario.', + fr: "Un formulaire rempli au démarrage de chaque session dans ce groupe. La session n'est créée qu'une fois le formulaire soumis." + }), + kind: 'string', + label: t({ en: 'Session Instrument', es: 'Instrumento de sesión', fr: 'Instrument de session' }), + options: { + [NO_SESSION_INSTRUMENT]: t({ en: 'None', es: 'Ninguno', fr: 'Aucun' }), + ...sessionInstrumentOptions + }, + variant: 'select' + } + }, + title: t({ en: 'Starting a Session', es: 'Inicio de una sesión', fr: "Démarrage d'une session" }) } ]} initialValues={settingsInitialValues} @@ -807,9 +842,27 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => idValidationRegexErrorMessageFr: z.string().optional(), minimumAge: z.number().int().positive().optional(), minimumAgeApplied: z.boolean().optional(), + sessionInstrumentId: z.string().optional(), subjectIdDisplayLength: z.number().int().min(1).optional() }) .check((ctx) => { + const { sessionInstrumentId } = ctx.value; + if ( + sessionInstrumentId && + sessionInstrumentId !== NO_SESSION_INSTRUMENT && + !(selectedIds.has(sessionInstrumentId) || hiddenAccessibleIds.includes(sessionInstrumentId)) + ) { + ctx.issues.push({ + code: 'custom', + input: sessionInstrumentId, + message: t({ + en: "The session instrument must be one of the group's instruments. Select it above, or choose another session instrument.", + es: 'El instrumento de sesión debe ser uno de los instrumentos del grupo. Selecciónelo arriba o elija otro instrumento de sesión.', + fr: "L'instrument de session doit faire partie des instruments du groupe. Sélectionnez-le ci-dessus ou choisissez un autre instrument de session." + }), + path: ['sessionInstrumentId'] + }); + } if (ctx.value.minimumAgeApplied && !ctx.value.minimumAge) { ctx.issues.push({ code: 'custom', @@ -841,6 +894,8 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => fr: formData.idValidationRegexErrorMessageFr }, minimumAge: formData.minimumAgeApplied ? formData.minimumAge : null, + sessionInstrumentId: + formData.sessionInstrumentId === NO_SESSION_INSTRUMENT ? null : formData.sessionInstrumentId, subjectIdDisplayLength: formData.subjectIdDisplayLength } }); @@ -857,20 +912,20 @@ const RouteComponent = () => { const currentGroup = useAppStore((store) => store.currentGroup); const changeGroup = useAppStore((store) => store.changeGroup); const setupState = useSetupStateQuery(); + // The store holds the group as it was at sign-in, and a save sends back every setting the form was + // seeded with, so seeding it from that copy would undo any change made since. + const groupQuery = useGroupQuery(currentGroup?.id); + const group = groupQuery.data; const availableInstruments = instrumentInfoQuery.data; - const accessibleInstrumentIds = currentGroup?.accessibleInstrumentIds; - const instrumentRepoIds = currentGroup?.instrumentRepoIds; - const defaultIdentificationMethod = currentGroup?.settings.defaultIdentificationMethod; - const data = useMemo(() => { - if (!availableInstruments) { + if (!availableInstruments || !group) { return null; } - const accessibleSet = new Set(accessibleInstrumentIds ?? []); - const assignedRepos = new Set(instrumentRepoIds ?? []); + const accessibleSet = new Set(group.accessibleInstrumentIds); + const assignedRepos = new Set(group.instrumentRepoIds); const instruments: CategorizedInstruments = { form: [], interactive: [], series: [] }; const visibleIds = new Set(); @@ -903,12 +958,12 @@ const RouteComponent = () => { const seriesGroupId = instrument.kind === 'SERIES' ? (instrument.seriesGroupId ?? null) : null; const item: InstrumentItem = { authors: instrument.details.authors, - availability: buildSeriesAvailability({ currentGroup, instrumentKind: instrument.kind, seriesGroupId }), + availability: buildSeriesAvailability({ currentGroup: group, instrumentKind: instrument.kind, seriesGroupId }), createdAt: instrument.createdAt ?? null, description: instrument.details.description, id: instrument.id, internal: instrument.kind === 'SERIES' ? null : instrument.internal, - isDeletable: instrument.kind === 'SERIES' && seriesGroupId === currentGroup?.id, + isDeletable: instrument.kind === 'SERIES' && seriesGroupId === group.id, kind: instrument.kind, seriesItems: instrument.kind === 'SERIES' ? instrument.seriesItems : undefined, source, @@ -927,42 +982,31 @@ const RouteComponent = () => { // Preserve any accessible ids we are not displaying (defensive: e.g. instruments that failed to load). const hiddenAccessibleIds = [...accessibleSet].filter((id) => !visibleIds.has(id)); - const settings = currentGroup?.settings; + const settings = group.settings; const settingsInitialValues: SettingsValues = { - defaultIdentificationMethod, - idValidationRegex: settings?.idValidationRegex, - idValidationRegexErrorMessageEn: settings?.idValidationRegexErrorMessage?.en, - idValidationRegexErrorMessageFr: settings?.idValidationRegexErrorMessage?.fr, - minimumAge: settings?.minimumAge, - minimumAgeApplied: typeof settings?.minimumAge === 'number', - subjectIdDisplayLength: settings?.subjectIdDisplayLength + defaultIdentificationMethod: settings.defaultIdentificationMethod, + idValidationRegex: settings.idValidationRegex, + idValidationRegexErrorMessageEn: settings.idValidationRegexErrorMessage?.en, + idValidationRegexErrorMessageFr: settings.idValidationRegexErrorMessage?.fr, + minimumAge: settings.minimumAge, + minimumAgeApplied: typeof settings.minimumAge === 'number', + sessionInstrumentId: settings.sessionInstrumentId ?? NO_SESSION_INSTRUMENT, + subjectIdDisplayLength: settings.subjectIdDisplayLength }; const existingTitles = [...instruments.form, ...instruments.interactive, ...instruments.series].map( (item) => item.title ); - return currentGroup - ? { - existingTitles, - groupId: currentGroup.id, - hiddenAccessibleIds, - initialSelectedIds, - instruments, - settingsInitialValues - } - : null; - }, [ - accessibleInstrumentIds, - availableInstruments, - currentGroup?.id, - currentGroup?.name, - defaultIdentificationMethod, - instrumentRepoIds, - resolvedLanguage, - t, - currentGroup?.settings - ]); + return { + existingTitles, + groupId: group.id, + hiddenAccessibleIds, + initialSelectedIds, + instruments, + settingsInitialValues + }; + }, [availableInstruments, group, resolvedLanguage, t]); return ( @@ -990,5 +1034,12 @@ const RouteComponent = () => { }; export const Route = createFileRoute('/_app/group/manage')({ - component: RouteComponent + component: RouteComponent, + // Fetched even when cached, since the form is seeded once and saves every setting it was seeded with. + loader: async ({ context }) => { + const { currentGroup } = useAppStore.getState(); + if (currentGroup) { + await context.queryClient.fetchQuery(groupQueryOptions(currentGroup.id)); + } + } }); diff --git a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx index f02d046e9..254aa1fff 100644 --- a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx +++ b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx @@ -1,5 +1,6 @@ import type { FC } from 'react'; +import type { InstrumentSubmitHandler } from '@opendatacapture/react-core'; import type { Group } from '@opendatacapture/schemas/group'; import type { $CreateSessionData, Session } from '@opendatacapture/schemas/session'; import { act, cleanup, render, screen } from '@testing-library/react'; @@ -18,11 +19,18 @@ type StartSessionFormProps = { username?: string; }; +type SessionInstrumentStepProps = { + instrumentId: string; + onBack: () => void; + onSubmit: (result: Parameters[0]) => Promise; +}; + type Loader = (ctx: { context: { queryClient: { ensureQueryData: (options: object) => Promise } }; }) => Promise; type MockState = { + fetchedGroup: Group | null; isPending: boolean; locationState: undefined | { initialValues?: { [key: string]: unknown } }; store: { @@ -35,6 +43,7 @@ type MockState = { const mocks = vi.hoisted(() => { const state: MockState = { + fetchedGroup: null, isPending: false, locationState: undefined, store: { currentGroup: null, currentSession: null, currentUser: null, startSession: vi.fn() } @@ -42,6 +51,7 @@ const mocks = vi.hoisted(() => { return { ...state, mutateAsync: vi.fn(), + SessionInstrumentStep: vi.fn((_props: SessionInstrumentStepProps) =>
), StartSessionForm: vi.fn((_props: StartSessionFormProps) =>
) }; }); @@ -52,9 +62,14 @@ vi.mock('@tanstack/react-router', async (importOriginal) => ({ useLocation: () => ({ state: mocks.locationState }) })); vi.mock('@/components/StartSessionForm', () => ({ StartSessionForm: mocks.StartSessionForm })); +vi.mock('@/components/SessionInstrumentStep', () => ({ SessionInstrumentStep: mocks.SessionInstrumentStep })); vi.mock('@/hooks/useCreateSessionMutation', () => ({ useCreateSessionMutation: () => ({ isPending: mocks.isPending, mutateAsync: mocks.mutateAsync }) })); +vi.mock('@/hooks/useGroupQuery', async (importOriginal) => ({ + ...(await importOriginal()), + useGroupQuery: (groupId: string | undefined) => ({ data: groupId ? mocks.fetchedGroup : undefined }) +})); vi.mock('@/hooks/useSubjectCustomIdsQuery', async (importOriginal) => ({ ...(await importOriginal()), useSubjectCustomIdsQuery: () => ({ data: ['group-1$CUSTOM-1', 'CUSTOM-2'] }) @@ -99,6 +114,7 @@ const formProps = () => mocks.StartSessionForm.mock.lastCall![0]; describe('Route', () => { beforeEach(() => { + mocks.fetchedGroup = group; mocks.isPending = false; mocks.locationState = undefined; mocks.store.currentGroup = group; @@ -201,6 +217,115 @@ describe('Route', () => { }); }); + describe('with a session instrument', () => { + const details: $CreateSessionData = { + date: NOW, + groupId: 'group-1', + subjectData: { id: 'subject-1' }, + type: 'IN_PERSON' + }; + + const answers = { + data: { score: 1 }, + instrumentId: 'form-1', + kind: 'FORM' + } as Parameters[0]; + + const stepProps = () => mocks.SessionInstrumentStep.mock.lastCall![0]; + + const isDetailsFormHidden = () => screen.getByTestId('start-session-form').parentElement!.className === 'hidden'; + + const submitDetails = async (data = details) => { + await act(() => formProps().onSubmit(data)); + }; + + beforeEach(() => { + mocks.fetchedGroup = { ...group, settings: { ...group.settings, sessionInstrumentId: 'form-1' } }; + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it("should show the group's session instrument once the details are submitted, without starting the session", async () => { + render(); + await submitDetails(); + expect(stepProps().instrumentId).toBe('form-1'); + expect(isDetailsFormHidden()).toBe(true); + expect(mocks.mutateAsync).not.toHaveBeenCalled(); + }); + + it('should return to the details as they were entered when the clinician goes back, starting nothing', async () => { + render(); + const detailsForm = screen.getByTestId('start-session-form'); + await submitDetails(); + act(() => stepProps().onBack()); + expect(screen.queryByTestId('session-instrument-step')).toBeNull(); + expect(isDetailsFormHidden()).toBe(false); + // The same element, so the form was never remounted and kept what had been typed into it. + expect(screen.getByTestId('start-session-form')).toBe(detailsForm); + expect(mocks.mutateAsync).not.toHaveBeenCalled(); + }); + + it('should start the session with the answers once the instrument is submitted', async () => { + render(); + await submitDetails({ ...details, type: 'RETROSPECTIVE' }); + await act(() => stepProps().onSubmit(answers)); + expect(mocks.mutateAsync).toHaveBeenCalledWith({ + ...details, + sessionInstrumentAnswers: { data: { score: 1 }, instrumentId: 'form-1' }, + type: 'RETROSPECTIVE' + }); + expect(mocks.store.startSession).toHaveBeenCalledWith({ ...session, type: 'RETROSPECTIVE' }); + }); + + it('should date an in-person session when the instrument is submitted, since that is when it is created', async () => { + render(); + await submitDetails(); + const submittedAt = new Date(NOW.getTime() + 60 * 60 * 1000); + vi.useFakeTimers({ toFake: ['Date'] }); + vi.setSystemTime(submittedAt); + await act(() => stepProps().onSubmit(answers)); + expect(mocks.mutateAsync.mock.lastCall?.[0].date).toStrictEqual(submittedAt); + }); + + it('should offer the details again, not the instrument, for the next session', async () => { + const { rerender } = render(); + await submitDetails(); + await act(() => stepProps().onSubmit(answers)); + mocks.store.currentSession = session; + rerender(); + mocks.store.currentSession = null; + rerender(); + expect(screen.queryByTestId('session-instrument-step')).toBeNull(); + expect(isDetailsFormHidden()).toBe(false); + }); + + // The store holds the group from the sign-in token, which predates a session instrument chosen since. + it('should require the session instrument the group has now, not the one it had at sign-in', async () => { + mocks.store.currentGroup = group; + render(); + await submitDetails(); + expect(stepProps().instrumentId).toBe('form-1'); + }); + + it('should start the session at once when the group requires no session instrument', async () => { + mocks.fetchedGroup = group; + render(); + await submitDetails(); + expect(screen.queryByTestId('session-instrument-step')).toBeNull(); + expect(mocks.mutateAsync).toHaveBeenCalledWith(details); + }); + + it('should drop the details entered for another group when the clinician switches group', async () => { + const { rerender } = render(); + await submitDetails(); + mocks.store.currentGroup = { ...mocks.store.currentGroup!, id: 'group-2' }; + rerender(); + expect(screen.queryByTestId('session-instrument-step')).toBeNull(); + }); + }); + describe('loader', () => { it('should prefetch the custom ids of the current group', async () => { const ensureQueryData = vi.fn(() => Promise.resolve()); @@ -218,5 +343,18 @@ describe('Route', () => { expect.objectContaining({ queryKey: ['subjects', 'custom-ids', undefined] }) ); }); + + it('should prefetch the current group, so its session instrument is known before the details are submitted', async () => { + const ensureQueryData = vi.fn(() => Promise.resolve()); + await loader({ context: { queryClient: { ensureQueryData } } }); + expect(ensureQueryData).toHaveBeenCalledWith(expect.objectContaining({ queryKey: ['group', 'group-1'] })); + }); + + it('should fetch no group when none is selected', async () => { + mocks.store.currentGroup = null; + const ensureQueryData = vi.fn(() => Promise.resolve()); + await loader({ context: { queryClient: { ensureQueryData } } }); + expect(ensureQueryData).toHaveBeenCalledOnce(); + }); }); }); diff --git a/apps/web/src/routes/_app/session/start-session.tsx b/apps/web/src/routes/_app/session/start-session.tsx index 284850028..fd0556ff9 100644 --- a/apps/web/src/routes/_app/session/start-session.tsx +++ b/apps/web/src/routes/_app/session/start-session.tsx @@ -3,17 +3,25 @@ import React, { useEffect, useState } from 'react'; import { Card, Heading } from '@douglasneuroinformatics/libui/components'; import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; import type { FormTypes } from '@opendatacapture/runtime-core'; +import type { $CreateSessionData, $StartSessionData } from '@opendatacapture/schemas/session'; import { removeSubjectIdScope } from '@opendatacapture/subject-utils'; import { createFileRoute, useLocation } from '@tanstack/react-router'; import { AnimatePresence, motion } from 'motion/react'; import { PageHeader } from '@/components/PageHeader'; +import { SessionInstrumentStep } from '@/components/SessionInstrumentStep'; import { StartSessionForm } from '@/components/StartSessionForm'; import type { StartSessionFormData } from '@/components/StartSessionForm'; import { useCreateSessionMutation } from '@/hooks/useCreateSessionMutation'; +import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { subjectCustomIdsQueryOptions, useSubjectCustomIdsQuery } from '@/hooks/useSubjectCustomIdsQuery'; import { useAppStore } from '@/store'; +type PendingSession = { + details: $CreateSessionData; + sessionInstrumentId: string; +}; + const RouteComponent = () => { const currentGroup = useAppStore((store) => store.currentGroup); const currentSession = useAppStore((store) => store.currentSession); @@ -27,10 +35,13 @@ const RouteComponent = () => { const [initialValues, setInitialValues] = useState>( location.state?.initialValues ?? defaultInitialValues ); + const [pendingSession, setPendingSession] = useState(null); const { t } = useTranslation('session'); const createSessionMutation = useCreateSessionMutation(); const subjectCustomIdsQuery = useSubjectCustomIdsQuery({ params: { groupId: currentGroup?.id } }); + // The store holds the group as it was at sign-in, so a session instrument chosen since is read fresh. + const groupQuery = useGroupQuery(currentGroup?.id); const customSubjectIds = subjectCustomIdsQuery.data.map(removeSubjectIdScope); @@ -40,6 +51,17 @@ const RouteComponent = () => { } }, [currentSession]); + // The details name the group they were entered in, so they must not start a session after a switch. + useEffect(() => { + setPendingSession(null); + }, [currentGroup?.id]); + + const createSession = async (data: $StartSessionData) => { + const session = await createSessionMutation.mutateAsync(data); + setPendingSession(null); + startSession({ ...session, type: data.type }); + }; + return ( @@ -48,15 +70,37 @@ const RouteComponent = () => { {currentSession === null && ( - { - const session = await createSessionMutation.mutateAsync(formData); - startSession({ ...session, type: formData.type }); + // Kept mounted behind the session instrument, so going back finds the details as they were entered. +
+ { + const sessionInstrumentId = groupQuery.data?.settings.sessionInstrumentId; + if (sessionInstrumentId) { + setPendingSession({ details, sessionInstrumentId }); + return; + } + await createSession(details); + }} + /> +
+ )} + {currentSession === null && pendingSession && ( + setPendingSession(null)} + onSubmit={async (result) => { + const { details } = pendingSession; + await createSession({ + ...details, + // An in-person session is dated when it is created, which is now that its form is submitted. + date: details.type === 'IN_PERSON' ? new Date() : details.date, + sessionInstrumentAnswers: { data: result.data, instrumentId: result.instrumentId } + }); }} /> )} @@ -124,6 +168,9 @@ export const Route = createFileRoute('/_app/session/start-session')({ component: RouteComponent, loader: async ({ context }) => { const { currentGroup } = useAppStore.getState(); - await context.queryClient.ensureQueryData(subjectCustomIdsQueryOptions({ params: { groupId: currentGroup?.id } })); + await Promise.all([ + context.queryClient.ensureQueryData(subjectCustomIdsQueryOptions({ params: { groupId: currentGroup?.id } })), + currentGroup ? context.queryClient.ensureQueryData(groupQueryOptions(currentGroup.id)) : null + ]); } }); diff --git a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx index 205aa86b0..fe452146c 100644 --- a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx +++ b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx @@ -80,6 +80,10 @@ The default Standard User role does not see Manage Group. Choose the default identification method and configure the ID validation pattern and validation messages. +6. **Choose a session instrument, if any** + + A group can require one form to be completed as part of starting every session. Set **Session Instrument** to that form, or to **None**. Only a form the group can access can be chosen, and it must stay accessible while it is the session instrument. When an administrator uploads a new edition of the form, the group requires the new edition. + ## Start a Session @@ -102,7 +106,11 @@ Use **Start Session** to begin work with a subject. Use an in-person session for new data collection; it is dated when it starts. Use a retrospective session when entering data that was collected earlier using another system, and enter the date and time the data was collected. -4. **Confirm the session is active** +4. **Complete the session instrument, if the group has one** + + When the group requires a session instrument, it opens once the session details are submitted. The session starts only when the form is submitted, and its answers are saved as a record of the session. **Back** returns to the session details; leaving saves nothing. + +5. **Confirm the session is active** After the session starts, ODC shows the active session in the sidebar. diff --git a/packages/schemas/src/group/__tests__/group.test.ts b/packages/schemas/src/group/__tests__/group.test.ts index 281ec11b7..94e7a3cee 100644 --- a/packages/schemas/src/group/__tests__/group.test.ts +++ b/packages/schemas/src/group/__tests__/group.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest'; -import { $UpdateGroupData } from '../group.js'; +import { $CreateGroupData, $UpdateGroupData } from '../group.js'; describe('$UpdateGroupData', () => { it('should require expectedUpdatedAt when emailTemplates is included', () => { @@ -26,3 +26,14 @@ describe('$UpdateGroupData', () => { } ); }); + +describe('$CreateGroupData', () => { + it('should drop a session instrument, so a group is never created requiring one it cannot access', () => { + const data = $CreateGroupData.parse({ + name: 'New Group', + settings: { defaultIdentificationMethod: 'CUSTOM_ID', sessionInstrumentId: 'instrument-1' }, + type: 'RESEARCH' + }); + expect(data.settings).not.toHaveProperty('sessionInstrumentId'); + }); +}); diff --git a/packages/schemas/src/group/group.ts b/packages/schemas/src/group/group.ts index 10836001b..2de64395d 100644 --- a/packages/schemas/src/group/group.ts +++ b/packages/schemas/src/group/group.ts @@ -8,6 +8,7 @@ const $GroupSettings = z.object({ idValidationRegex: $RegexString.nullish(), idValidationRegexErrorMessage: $LocalizedString.nullish(), minimumAge: z.number().int().positive().nullish(), + sessionInstrumentId: z.string().nullish(), subjectIdDisplayLength: z.number().nullish() }); @@ -50,7 +51,9 @@ export const $Group = $BaseModel.extend({ export type $CreateGroupData = z.infer; export const $CreateGroupData = z.object({ name: z.string().min(1), - settings: $GroupSettings.optional(), + // The session instrument must be one the group can access, which is checked only when a group is + // updated, so a group is created without one. + settings: $GroupSettings.omit({ sessionInstrumentId: true }).optional(), type: $GroupType }); diff --git a/packages/schemas/src/session/session.ts b/packages/schemas/src/session/session.ts index 2c24851a2..e51c0e878 100644 --- a/packages/schemas/src/session/session.ts +++ b/packages/schemas/src/session/session.ts @@ -1,6 +1,6 @@ import { z } from 'zod/v4'; -import { $BaseModel, $DateLike } from '../core/core.js'; +import { $BaseModel, $DateLike, $Json } from '../core/core.js'; import { $CreateSubjectData, $Subject } from '../subject/subject.js'; export type SessionType = z.infer; @@ -25,6 +25,12 @@ export const $CreateSessionData = z.object({ username: z.string().nullish() }); +export type $StartSessionData = z.infer; +export const $StartSessionData = $CreateSessionData.extend({ + // Required exactly when the session's group has a session instrument. + sessionInstrumentAnswers: z.object({ data: $Json, instrumentId: z.string() }).optional() +}); + export type SessionWithUser = Session & { user: null | { username?: null | string; diff --git a/testing/src/pages/_app/session/start-session.page.ts b/testing/src/pages/_app/session/start-session.page.ts index 8a7054c9c..a772d0372 100644 --- a/testing/src/pages/_app/session/start-session.page.ts +++ b/testing/src/pages/_app/session/start-session.page.ts @@ -8,6 +8,10 @@ export class StartSessionPage extends AppPage { readonly pageHeader: Locator; readonly selectField: Locator; readonly sessionForm: Locator; + /** Returns from the group's session instrument to the session details. */ + readonly sessionInstrumentBackButton: Locator; + /** The form a group requires as part of starting a session, shown once the details are submitted. */ + readonly sessionInstrumentStep: Locator; /** The hidden native select that carries the value; `sexTrigger` is the control a user sees. */ readonly sexField: Locator; readonly sexTrigger: Locator; @@ -20,6 +24,8 @@ export class StartSessionPage extends AppPage { super(page); this.pageHeader = page.getByTestId('page-header'); this.sessionForm = page.getByTestId('start-session-form'); + this.sessionInstrumentBackButton = page.getByTestId('session-instrument-back'); + this.sessionInstrumentStep = page.getByTestId('session-instrument-step'); this.selectField = page.locator('[name="subjectIdentificationMethod"]'); this.successMessage = page.getByRole('heading', { name: 'Session Successfully Started' }); this.errorMessages = page.getByTestId('error-message-text'); diff --git a/testing/src/specs/start-session.spec.ts b/testing/src/specs/start-session.spec.ts index fdd515c71..3b0750038 100644 --- a/testing/src/specs/start-session.spec.ts +++ b/testing/src/specs/start-session.spec.ts @@ -1,3 +1,4 @@ +import { RenderInstrumentPage } from '../pages/_app/instruments/render/$id.page'; import { StartSessionPage } from '../pages/_app/session/start-session.page'; import { expect, test } from '../support/fixtures'; @@ -79,6 +80,56 @@ test.describe('start session', () => { }); }); +// A group can require one form to be completed as part of starting a session. The session is created +// only once that form is submitted, so going back to the details creates nothing. +test.describe('session instrument', () => { + test("should start a session only once the group's session instrument is submitted, recording its answers", async ({ + api, + authenticateAs, + page, + uniqueId + }) => { + const group = await api.createGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_ID' } }); + const instrumentId = await api.findInstrumentIdByName('DNP_HAPPINESS_QUESTIONNAIRE'); + await api.updateGroup(group.id, { settings: { sessionInstrumentId: instrumentId } }); + const { credentials } = await api.createUser({ basePermissionLevel: 'STANDARD', groupIds: [group.id] }); + await authenticateAs(credentials); + + const sessionRequests: string[] = []; + page.on('request', (request) => { + if (request.url().endsWith('/v1/sessions') && request.method() === 'POST') { + sessionRequests.push(request.url()); + } + }); + + const startSessionPage = new StartSessionPage(page); + await startSessionPage.goto('/session/start-session'); + await startSessionPage.selectIdentificationMethod('CUSTOM_ID'); + await startSessionPage.typeSubjectId(`intake-${uniqueId}`); + await startSessionPage.dismissSubjectIdOptions(); + await startSessionPage.submitForm(); + await expect(startSessionPage.sessionInstrumentStep).toBeVisible(); + + await startSessionPage.sessionInstrumentBackButton.click(); + await expect(startSessionPage.subjectIdField).toHaveValue(`intake-${uniqueId}`); + expect(sessionRequests).toHaveLength(0); + await startSessionPage.submitForm(); + + const instrumentPage = new RenderInstrumentPage(page); + await instrumentPage.begin(); + await instrumentPage.completeHappinessQuestionnaire(); + const sessionCreated = page.waitForResponse( + (response) => response.url().endsWith('/v1/sessions') && response.request().method() === 'POST' + ); + await instrumentPage.submit(); + const session = (await (await sessionCreated).json()) as { id: string; subjectId: string }; + await expect(startSessionPage.successMessage).toBeVisible(); + + const records = await api.findRecordsBySubject(session.subjectId); + expect(records).toMatchObject([{ instrumentId, sessionId: session.id }]); + }); +}); + // The date picker opens on the browser's current month, so the clock is fixed to a known day; the // timezone makes the stored instant, which is what the API receives, the same wherever the suite runs. test.describe('retrospective session time', () => { diff --git a/testing/src/support/api-client.ts b/testing/src/support/api-client.ts index 047ed99d4..99bf3197e 100644 --- a/testing/src/support/api-client.ts +++ b/testing/src/support/api-client.ts @@ -3,7 +3,7 @@ import { AUDIT_LOGS_MAX_PAGE_SIZE } from '@opendatacapture/schemas/audit'; import type { $AuditLog, $AuditLogAction, $AuditLogsPage } from '@opendatacapture/schemas/audit'; import type { $LoginCredentials } from '@opendatacapture/schemas/auth'; import type { Permissions } from '@opendatacapture/schemas/core'; -import type { $CreateGroupData, Group } from '@opendatacapture/schemas/group'; +import type { $CreateGroupData, $UpdateGroupData, Group } from '@opendatacapture/schemas/group'; import type { InstrumentInfo } from '@opendatacapture/schemas/instrument'; import type { $CreateInstrumentRecordData, @@ -321,6 +321,15 @@ export class ApiClient { return this.putUserPermissions(id, { kind: 'custom', permissions }); } + /** Updates a group as admin, for settings a spec needs in place before a user signs in to it. */ + async updateGroup(id: string, data: $UpdateGroupData): Promise { + return this.expectJson( + this.request.patch(`${API}/groups/${id}`, { data, headers: this.authHeaders }), + 200, + `update group '${id}'` + ); + } + /** * Bulk-creates one record per entry, and with them the subjects and sessions they name. Returns * the records the api reports created, which the upload contract scopes to this request alone. From 2204b3edeb3a894c81e5277e04ff9bb39b51ae3c Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:32:59 -0500 Subject: [PATCH 05/19] test(subject-utils): pin the name hash to its known outputs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No test pinned an actual digest: the existing ones compare generateSubjectHash with itself, so a change to its output would pass. Each new case hard-codes the digest the current code produces, checked against an independent SHA-256 of the string it hashes, and covers what the normalization really does: accents and ligatures are spelled out, plain hyphens are removed, while spaces (trailing ones included), apostrophes and a non-breaking hyphen are kept, 李 and 里 both become "Li ", and the date is the UTC calendar day. Co-Authored-By: Claude Opus 5.5 --- .../subject-utils/src/__tests__/index.test.ts | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/packages/subject-utils/src/__tests__/index.test.ts b/packages/subject-utils/src/__tests__/index.test.ts index 34740c9d9..4bc494b42 100644 --- a/packages/subject-utils/src/__tests__/index.test.ts +++ b/packages/subject-utils/src/__tests__/index.test.ts @@ -1,3 +1,4 @@ +import type { ClinicalSubjectIdentificationData } from '@opendatacapture/schemas/subject'; import { describe, expect, it } from 'vitest'; import { @@ -48,6 +49,76 @@ describe('generateSubjectHash', () => { it('should reject a sex that is neither MALE nor FEMALE', async () => { await expect(generateSubjectHash({ ...validIdentificationData, sex: 'OTHER' as any })).rejects.toThrow(/sex/); }); + + describe('known outputs, which are the stored ids of existing subjects', () => { + const digestOf = (data: Partial) => { + return generateSubjectHash({ ...validIdentificationData, ...data }); + }; + + it('should hash Jane Doe, born 1990-01-01, female, as JANEDOE19900101FEMALE', async () => { + await expect(digestOf({})).resolves.toBe('520be817915752b50f418a743a54b692ce8e2a0a3421931598ffad246182568f'); + }); + it('should hash the sex, so a male Jane Doe is another subject', async () => { + await expect(digestOf({ sex: 'MALE' })).resolves.toBe( + 'a4c3acc853e01af7d008cef43cd706e7172546adab038253227cb508f914dff2' + ); + }); + it('should hash the UTC date of birth, so 23:00 at UTC-5 counts as the next day', async () => { + await expect(digestOf({ dateOfBirth: new Date('1990-01-01T23:00:00.000-05:00') })).resolves.toBe( + '69a9b6a4c7f6ea5aa909bf49de9b3255f545ee73198f35c73591b92597e5a9e2' + ); + }); + it('should ignore accents, so Jané is the same subject as Jane', async () => { + await expect(digestOf({ firstName: 'Jané' })).resolves.toBe( + '520be817915752b50f418a743a54b692ce8e2a0a3421931598ffad246182568f' + ); + }); + it('should spell out a ligature, so Lebœuf hashes as LEBOEUF', async () => { + await expect(digestOf({ lastName: 'Lebœuf' })).resolves.toBe( + 'b6b01685562db0f6a70e2f733d5bb69a324606a3a2b453bdd2cd188366ab3ff7' + ); + }); + it('should hash Leboeuf as LEBOEUF, so it is the same subject as Lebœuf', async () => { + await expect(digestOf({ lastName: 'Leboeuf' })).resolves.toBe( + 'b6b01685562db0f6a70e2f733d5bb69a324606a3a2b453bdd2cd188366ab3ff7' + ); + }); + it('should remove a plain hyphen, so Jean-Paul hashes as JEANPAUL', async () => { + await expect(digestOf({ firstName: 'Jean-Paul' })).resolves.toBe( + '8665e6f202aacdd33ed13e7ee8b009c0a8ca251b38538cb4b67726bd32e74a22' + ); + }); + it('should keep a space, so Jean Paul hashes as JEAN PAUL', async () => { + await expect(digestOf({ firstName: 'Jean Paul' })).resolves.toBe( + '121a8f52d912a1a528a2e9ab64161565b30e49b2a8e2d4854f8eb7724fd6c2fa' + ); + }); + it('should keep a non-breaking hyphen as a plain one, so Jean\u2011Paul hashes as JEAN-PAUL', async () => { + await expect(digestOf({ firstName: 'Jean\u2011Paul' })).resolves.toBe( + '3e5e80408aff02aabe1801569cb21e2aadb8d28db7914f392df0ce16fc698dba' + ); + }); + it('should keep a trailing space, so Jean-Paul followed by a space hashes as JEANPAUL with the space', async () => { + await expect(digestOf({ firstName: 'Jean-Paul ' })).resolves.toBe( + 'f0d8a30dafa14c148c715b6254ba6a9756d3a475e4d18491be6f2e6a2cdfd99f' + ); + }); + it("should keep an apostrophe, so O'Brien hashes as O'BRIEN", async () => { + await expect(digestOf({ lastName: "O'Brien" })).resolves.toBe( + '93cf2857f689f1868ddd4792bcb19fab10ff46027fa453f27c249578f8739e0e' + ); + }); + it('should romanize 李 as Li followed by a space', async () => { + await expect(digestOf({ firstName: '李' })).resolves.toBe( + '0062948bce4a918ea435a2412dd14aa3e5a7b64980a390155946d6f7104752f3' + ); + }); + it('should romanize 里 as Li too, so it is the same subject as 李', async () => { + await expect(digestOf({ firstName: '里' })).resolves.toBe( + '0062948bce4a918ea435a2412dd14aa3e5a7b64980a390155946d6f7104752f3' + ); + }); + }); }); describe('isSubjectWithPersonalInfo', () => { From e13ac829e6e11c48122fdd97393c77bd6b1da5f0 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:33:45 -0500 Subject: [PATCH 06/19] build(subject-utils): pin transliteration to exactly 2.6.1 The name hash transliterates its input, so the library's mapping table is part of every stored Personal Info id. A caret range let a minor release change that table, and with it what an existing subject's details hash to. The lockfile already resolved 2.6.1; only the specifier changes. Co-Authored-By: Claude Opus 5.5 --- packages/subject-utils/package.json | 2 +- pnpm-lock.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/subject-utils/package.json b/packages/subject-utils/package.json index d2940ee6b..0c571c99a 100644 --- a/packages/subject-utils/package.json +++ b/packages/subject-utils/package.json @@ -14,7 +14,7 @@ "@douglasneuroinformatics/libcrypto": "catalog:", "@opendatacapture/runtime-internal": "workspace:*", "@opendatacapture/schemas": "workspace:*", - "transliteration": "^2.3.5" + "transliteration": "2.6.1" }, "devDependencies": { "type-fest": "workspace:type-fest__4.x@*" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b8abf9463..98a4397d8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1284,7 +1284,7 @@ importers: specifier: workspace:* version: link:../schemas transliteration: - specifier: ^2.3.5 + specifier: 2.6.1 version: 2.6.1 devDependencies: type-fest: From 85936796523af4a0ae3ef611dd6fa0f065796540 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:34:45 -0500 Subject: [PATCH 07/19] fix(web): say what the name hash really ignores in the name help text The first-name and last-name help text on Start Session and the datahub lookup said white space and special characters are removed. The hash removes only plain hyphens: spaces, apostrophes and other punctuation are part of it, so "Jean Paul" and "Jean-Paul" are two subjects. The text now says that accents, letter case and plain hyphens are ignored, and that spaces, even leading or trailing ones, apostrophes and other punctuation count. The hash itself is unchanged: its output is every Personal Info subject's stored id. Refs #1684 Co-Authored-By: Claude Opus 5.5 --- apps/web/src/translations/common.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/web/src/translations/common.json b/apps/web/src/translations/common.json index 14962ecd5..ca7493306 100644 --- a/apps/web/src/translations/common.json +++ b/apps/web/src/translations/common.json @@ -239,9 +239,9 @@ "subjectIdentification": { "firstName": { "description": { - "en": "The subject's first name, as provided by their birth certificate. For the purpose of identification, white space, special characters, and accents are removed, with accented characters treated as a fixed ASCII transliteration.", - "es": "El nombre del sujeto, según su certificado de nacimiento. A efectos de identificación, se eliminan los espacios en blanco, los caracteres especiales y los acentos, y los caracteres acentuados se tratan como una transliteración ASCII fija.", - "fr": "Le prénom du sujet, tel qu'il figure dans son acte de naissance. Pour les besoins de l'identification, les espaces blancs, les caractères spéciaux et les accents sont supprimés, les caractères accentués étant traités comme une translittération ASCII fixe." + "en": "The subject's first name, as provided by their birth certificate. For identification, accents, letter case and plain hyphens (-) are ignored, but spaces (even at the start or end), apostrophes and all other punctuation count, so enter the name the same way every time.", + "es": "El nombre del sujeto, según su certificado de nacimiento. A efectos de identificación, se ignoran los acentos, las mayúsculas y minúsculas y los guiones simples (-), pero cuentan los espacios (incluso al principio o al final), los apóstrofos y cualquier otro signo de puntuación, así que escriba el nombre siempre de la misma manera.", + "fr": "Le prénom du sujet, tel qu'il figure dans son acte de naissance. Pour l'identification, les accents, les majuscules et minuscules et les traits d'union simples (-) sont ignorés, mais les espaces (même au début ou à la fin), les apostrophes et toute autre ponctuation comptent : saisissez donc le prénom toujours de la même façon." }, "label": { "en": "First Name", @@ -251,9 +251,9 @@ }, "lastName": { "description": { - "en": "The subject's last name, as provided by their birth certificate. For the purpose of identification, white space, special characters, and accents are removed, with accented characters treated as their ASCII equivalents.", - "es": "El apellido del sujeto, según su certificado de nacimiento. A efectos de identificación, se eliminan los espacios en blanco, los caracteres especiales y los acentos, y los caracteres acentuados se tratan como sus equivalentes ASCII.", - "fr": "Le nom de famille du sujet, tel qu'il figure dans son acte de naissance. Aux fins d'identification, les espaces blancs, les caractères spéciaux et les accents sont supprimés, les caractères accentués étant traités comme leurs équivalents ASCII." + "en": "The subject's last name, as provided by their birth certificate. For identification, accents, letter case and plain hyphens (-) are ignored, but spaces (even at the start or end), apostrophes and all other punctuation count, so enter the name the same way every time.", + "es": "El apellido del sujeto, según su certificado de nacimiento. A efectos de identificación, se ignoran los acentos, las mayúsculas y minúsculas y los guiones simples (-), pero cuentan los espacios (incluso al principio o al final), los apóstrofos y cualquier otro signo de puntuación, así que escriba el apellido siempre de la misma manera.", + "fr": "Le nom de famille du sujet, tel qu'il figure dans son acte de naissance. Pour l'identification, les accents, les majuscules et minuscules et les traits d'union simples (-) sont ignorés, mais les espaces (même au début ou à la fin), les apostrophes et toute autre ponctuation comptent : saisissez donc le nom toujours de la même façon." }, "label": { "en": "Last Name", From 6f7ebe42418201ce01cba926a312030a1d657b11 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:35:48 -0500 Subject: [PATCH 08/19] docs: describe what the name hash really ignores MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The hash-based identification page said white space and special characters are removed, that non-Latin names are refused, and that a private key held by the server is added to the input. None of that is what generateSubjectHash does. The page now lists what is ignored (letter case, plain hyphens, accents and ligatures, with other scripts romanized), what still counts (spaces, apostrophes, other dashes and punctuation), says no secret is added, and replaces the example with the real input and digest for René Tremblay. The French docs mirror only the introduction, so there is no French page to update. Refs #1684 Co-Authored-By: Claude Opus 5.5 --- .../en/4-concepts/4.2-hash-based-identification.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/en/4-concepts/4.2-hash-based-identification.md b/docs/en/4-concepts/4.2-hash-based-identification.md index 1103f8461..07b3ef2b8 100644 --- a/docs/en/4-concepts/4.2-hash-based-identification.md +++ b/docs/en/4-concepts/4.2-hash-based-identification.md @@ -35,18 +35,24 @@ To illustrate how this process works, suppose we have the following information: | Date of Birth | 1980-01-01 | | Sex | female | -Before adding this information to our database, we thoroughly validate and process the provided inputs. Specifically, we standardize the format of first and last names by converting any accented Latin characters to their non-accented [ASCII](https://en.wikipedia.org/wiki/ASCII) equivalent and capitalizing all characters. Non-Latin characters are not accepted and the user must provide a Latin representation of the name. Additionally, we verify that the date of birth adheres to the ISO 8601 standard and that the sex field is accurately filled with "male" or "female". +Your browser first checks that every field is filled in, that the date of birth is a valid date and that the sex is "male" or "female". It then joins the first name, the last name, the date of birth (written as YYYY-MM-DD) and the sex into one string, and standardizes it: -If the inputs appear to be valid, the inputs are concatenated together alongside a private key, which is an additional string of characters that is stored in the memory of our server. This is done to prevent an adversary from determining if an individual is in the database, in the unlikely event of a data breach. +- Letters are converted to uppercase, so letter case is ignored. +- Plain hyphens (-) are removed, so "Jean-Paul" and "JeanPaul" are the same name. +- Accented letters and ligatures are replaced by their unaccented [ASCII](https://en.wikipedia.org/wiki/ASCII) equivalents, so "René" and "Rene" are the same name, as are "Lebœuf" and "Leboeuf". Names in other scripts are converted to Latin letters, which can give two different names the same spelling: "李" and "里" both become "Li". + +Nothing else is removed. Spaces, apostrophes, other dashes and all other punctuation are part of the input, so "Jean Paul" and "Jean-Paul", or "O'Brien" and "OBrien", identify two different people. A space typed at the start or end of a name counts too, although a bulk assignment file has those removed from each cell first. Enter a name the same way every time. + +No secret is added to the input, so anyone who knows a person's name, date of birth and sex can compute the same identifier. - + - +
InputRENE_TREMBLAY_1980-01-01_female_FOORENETREMBLAY19800101FEMALE
Output70c7a252fe82c829c08a8f26377dc600c18966eff2a294e724863480559561fc38906490aa2ee5c844da597b70f21c2865e143ca12719cc51afbdaa5e293c22c
From de18aba2325d62145aae1f9cf38c346fc61aaf10 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:38:45 -0500 Subject: [PATCH 09/19] refactor: move the subject id scoping rule into subject-utils How an id a person typed or pasted becomes the id it is stored under lived in the bulk assignment wizard as toStoredSubjectId and GENERATED_ID, so CSV upload never used it. It moves to subject-utils beside the classifier it is built on, inferSubjectIdentificationMethod: a bare 64-character lowercase hex digest is a name hash and everything else a custom id. Only a custom id without a `$` is scoped to the group. GENERATED_ID ignored case, the new rule does not. A name hash is always lowercase, so an uppercase digest is a custom id and is now scoped. Bulk matching is unchanged: an uppercase value never matched a stored lowercase hash, and the prefix match compares unscoped ids, so a scoped paste still finds the same subjects. The wizard always has a group, so resolveSubjectIds and resolveEmailList now require its name, and the branch that passed ids through without one is gone. Refs #1751 Co-Authored-By: Claude Opus 5.5 --- .../utils/__tests__/bulk-assignments.test.ts | 28 ++++++++++--- apps/web/src/utils/bulk-assignments.ts | 26 +++--------- .../subject-utils/src/__tests__/index.test.ts | 41 ++++++++++++++++++- packages/subject-utils/src/index.ts | 21 +++++++++- 4 files changed, 87 insertions(+), 29 deletions(-) diff --git a/apps/web/src/utils/__tests__/bulk-assignments.test.ts b/apps/web/src/utils/__tests__/bulk-assignments.test.ts index ee89aab4b..ff0d2fe79 100644 --- a/apps/web/src/utils/__tests__/bulk-assignments.test.ts +++ b/apps/web/src/utils/__tests__/bulk-assignments.test.ts @@ -30,7 +30,9 @@ const resolvedIds = async (...args: Parameters) => { return (await resolveSubjectIds(...args)).matched.map(({ id }) => id); }; -const resolve = (input: string, maxSubjects = 500) => resolvedIds(parseDelimitedText(input), { maxSubjects }); +const resolve = (input: string, maxSubjects = 500) => { + return resolvedIds(parseDelimitedText(input), { groupName: 'Depression Clinic', maxSubjects }); +}; /** The errors carried by a rejected parse, so a test can assert on row numbers and wording. */ const failureOf = async (run: () => unknown) => { @@ -126,8 +128,11 @@ describe('parseDelimitedText', () => { }); describe('resolveSubjectIds', () => { - it('should return ids unchanged in ID mode', async () => { - await expect(resolve('subjectId\nsubject-1\nsubject-2')).resolves.toEqual(['subject-1', 'subject-2']); + it('should return one stored id per row in ID mode, in file order', async () => { + await expect(resolve('subjectId\nsubject-1\nsubject-2')).resolves.toEqual([ + 'Depression_Clinic$subject-1', + 'Depression_Clinic$subject-2' + ]); }); it('should derive ids matching real generateSubjectHash output, never a reimplementation of it', async () => { @@ -252,8 +257,15 @@ describe('resolveSubjectIds', () => { ]); }); - it('should pass values through unchanged when no group is known', async () => { - await expect(resolvedIds(idCsv('ex_111'), { maxSubjects: 10 })).resolves.toEqual(['ex_111']); + it('should match an uppercase hex custom identifier to its scoped stored id, since no name hash is uppercase', async () => { + const customId = 'A'.repeat(64); + await expect( + resolvedIds(idCsv(customId), { + groupName: 'Depression Clinic', + knownSubjectIds: [`Depression_Clinic$${customId}`, 'a'.repeat(64)], + maxSubjects: 10 + }) + ).resolves.toEqual([`Depression_Clinic$${customId}`]); }); it('should match a truncated identifier against known subjects by prefix', async () => { @@ -303,7 +315,11 @@ describe('resolveSubjectIds', () => { it('should report personal information the group cannot place by row, never by name', async () => { const parsed = parseDelimitedText('firstName,lastName,dateOfBirth,sex\nJean,Tremblay,2000-01-01,M'); - const resolution = await resolveSubjectIds(parsed, { knownSubjectIds: [], maxSubjects: 10 }); + const resolution = await resolveSubjectIds(parsed, { + groupName: 'Depression Clinic', + knownSubjectIds: [], + maxSubjects: 10 + }); expect(resolution).toEqual({ ambiguousRows: [], matched: [], unknownRows: [2] }); }); }); diff --git a/apps/web/src/utils/bulk-assignments.ts b/apps/web/src/utils/bulk-assignments.ts index a6c79e317..b6186a59a 100644 --- a/apps/web/src/utils/bulk-assignments.ts +++ b/apps/web/src/utils/bulk-assignments.ts @@ -1,7 +1,7 @@ import { toBasicISOString, toLocalISOString } from '@douglasneuroinformatics/libjs'; import type { BulkAssignmentFailure } from '@opendatacapture/schemas/assignment'; import { $Sex } from '@opendatacapture/schemas/subject'; -import { encodeScopedSubjectId, generateSubjectHash, removeSubjectIdScope } from '@opendatacapture/subject-utils'; +import { generateSubjectHash, removeSubjectIdScope, toStoredSubjectId } from '@opendatacapture/subject-utils'; import Papa from 'papaparse'; /** @@ -47,22 +47,6 @@ const SEX_ALIASES: { [key: string]: 'FEMALE' | 'MALE' } = { const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/; -const GENERATED_ID = /^[0-9a-f]{64}$/i; - -/** - * Turn an identifier as a person would write it into the one the record is stored under. - * - * A custom identifier is stored scoped to its group (`Group$id`) but is shown, exported and spoken - * about without that prefix, so a user pasting what they see would otherwise never match. A digest - * is never scoped, and an already-scoped value is left alone. - */ -function toStoredSubjectId(value: string, groupName: string | undefined): string { - if (!groupName || value.includes('$') || GENERATED_ID.test(value)) { - return value; - } - return encodeScopedSubjectId(value, { groupName }); -} - /** * The outcome of looking an identifier up among a group's subjects. Ambiguous is kept apart from * unknown because the two are different mistakes: one identifier is too short to name anybody in @@ -410,7 +394,7 @@ type SubjectIdResolution = { */ async function resolveSubjectIds( result: BulkParseResult, - { groupName, knownSubjectIds, maxSubjects }: { groupName?: string; knownSubjectIds?: string[]; maxSubjects: number } + { groupName, knownSubjectIds, maxSubjects }: { groupName: string; knownSubjectIds?: string[]; maxSubjects: number } ): Promise { const errors: BulkParseError[] = []; const resolved: ResolvedRow[] = []; @@ -426,7 +410,7 @@ async function resolveSubjectIds( errors.push({ message: 'Missing subject ID', row: rowNumber }); continue; } - const stored = toStoredSubjectId(value, groupName); + const stored = toStoredSubjectId(value, { groupName }); if (!knownSubjectIds) { resolved.push({ id: stored, rowNumber }); continue; @@ -548,7 +532,7 @@ type EmailListResolution = { function resolveEmailList( rows: { [key: string]: string }[], mapping: Partial<{ [key: string]: CanonicalField }>, - { groupName, knownSubjectIds }: { groupName?: string; knownSubjectIds: string[] } + { groupName, knownSubjectIds }: { groupName: string; knownSubjectIds: string[] } ): EmailListResolution { const subjectIdHeader = Object.keys(mapping).find((header) => mapping[header] === 'subjectId'); const emailHeader = Object.keys(mapping).find((header) => mapping[header] === 'email'); @@ -564,7 +548,7 @@ function resolveEmailList( if (!rawId) { continue; } - const stored = toStoredSubjectId(rawId, groupName); + const stored = toStoredSubjectId(rawId, { groupName }); const match = matchKnownSubjectId(stored, knownSubjectIds); // An ambiguous identifier names nobody in particular, which is as unusable here as one naming // nobody at all, and the file spelled both the same way. diff --git a/packages/subject-utils/src/__tests__/index.test.ts b/packages/subject-utils/src/__tests__/index.test.ts index 4bc494b42..c80cf7172 100644 --- a/packages/subject-utils/src/__tests__/index.test.ts +++ b/packages/subject-utils/src/__tests__/index.test.ts @@ -4,8 +4,10 @@ import { describe, expect, it } from 'vitest'; import { encodeScopedSubjectId, generateSubjectHash, + inferSubjectIdentificationMethod, isSubjectWithPersonalInfo, - removeSubjectIdScope + removeSubjectIdScope, + toStoredSubjectId } from '../index.js'; const validIdentificationData = { @@ -15,6 +17,8 @@ const validIdentificationData = { sex: 'FEMALE' } as const; +const nameHash = '520be817915752b50f418a743a54b692ce8e2a0a3421931598ffad246182568f'; + describe('generateSubjectHash', () => { it('should hash valid clinical identification data to a deterministic string', async () => { await expect(generateSubjectHash(validIdentificationData)).resolves.toEqual( @@ -168,3 +172,38 @@ describe('removeSubjectIdScope', () => { expect(removeSubjectIdScope('My_Group$123')).toBe('123'); }); }); + +describe('inferSubjectIdentificationMethod', () => { + it('should read a bare 64-character lowercase hex digest as a name hash', () => { + expect(inferSubjectIdentificationMethod(nameHash)).toBe('PERSONAL_INFO'); + }); + it('should read an uppercase digest as a custom id, since a name hash is always lowercase', () => { + expect(inferSubjectIdentificationMethod(nameHash.toUpperCase())).toBe('CUSTOM_ID'); + }); + it('should read a truncated digest as a custom id', () => { + expect(inferSubjectIdentificationMethod(nameHash.slice(0, 63))).toBe('CUSTOM_ID'); + }); + it('should read a scoped digest as a custom id, since a name hash is never scoped', () => { + expect(inferSubjectIdentificationMethod(`My_Group$${nameHash}`)).toBe('CUSTOM_ID'); + }); + it('should read any other value as a custom id', () => { + expect(inferSubjectIdentificationMethod('ex_111')).toBe('CUSTOM_ID'); + }); +}); + +describe('toStoredSubjectId', () => { + it('should scope a custom id to the group, as Start Session stores it', () => { + expect(toStoredSubjectId('ex_111', { groupName: 'My Group' })).toBe('My_Group$ex_111'); + }); + it('should leave a name hash unscoped, so it names the subject every group shares', () => { + expect(toStoredSubjectId(nameHash, { groupName: 'My Group' })).toBe(nameHash); + }); + it('should scope an uppercase digest, which cannot be a name hash', () => { + expect(toStoredSubjectId(nameHash.toUpperCase(), { groupName: 'My Group' })).toBe( + `My_Group$${nameHash.toUpperCase()}` + ); + }); + it('should leave a value that already holds a scope alone', () => { + expect(toStoredSubjectId('Other_Group$ex_111', { groupName: 'My Group' })).toBe('Other_Group$ex_111'); + }); +}); diff --git a/packages/subject-utils/src/index.ts b/packages/subject-utils/src/index.ts index fbed0c747..920065103 100644 --- a/packages/subject-utils/src/index.ts +++ b/packages/subject-utils/src/index.ts @@ -1,10 +1,17 @@ import { sha256 } from '@douglasneuroinformatics/libcrypto'; -import type { ClinicalSubjectIdentificationData, Subject } from '@opendatacapture/schemas/subject'; +import type { + ClinicalSubjectIdentificationData, + Subject, + SubjectIdentificationMethod +} from '@opendatacapture/schemas/subject'; import { transliterate } from 'transliteration'; import type { SetNonNullable } from 'type-fest'; type SubjectPersonalInfo = Pick; +// libcrypto's sha256 writes each byte as two lowercase hex digits, so no stored name hash has an uppercase letter. +const PERSONAL_INFO_SUBJECT_ID_PATTERN = /^[0-9a-f]{64}$/; + function parseClinicalSubjectIdentificationData({ dateOfBirth, firstName, @@ -55,4 +62,16 @@ export function encodeScopedSubjectId(id: string, options: { groupName: string } return `${options.groupName.replaceAll(' ', '_')}$${id}`; } +export function inferSubjectIdentificationMethod(subjectId: string): SubjectIdentificationMethod { + return PERSONAL_INFO_SUBJECT_ID_PATTERN.test(subjectId) ? 'PERSONAL_INFO' : 'CUSTOM_ID'; +} + +export function toStoredSubjectId(enteredId: string, options: { groupName: string }): string { + // Only a custom id belongs to a group; a name hash names the same subject in every group. + if (enteredId.includes('$') || inferSubjectIdentificationMethod(enteredId) !== 'CUSTOM_ID') { + return enteredId; + } + return encodeScopedSubjectId(enteredId, options); +} + export { removeSubjectIdScope } from '@opendatacapture/runtime-internal'; From e19bdc141d967283bed14108939508945fb7d08b Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:39:24 -0500 Subject: [PATCH 10/19] fix(web): stop CSV upload scoping a name hash to the group CSV upload scoped every subject id to the current group, a Personal Info name hash included. A hash pasted from the datahub was stored as Group$, a second subject beside the real one, and the uploaded records went to it. Upload now applies the same rule as bulk assignments, toStoredSubjectId: a bare name hash is left as it is, and only a custom id is scoped. Refs #1751 Co-Authored-By: Claude Opus 5.5 --- apps/web/src/utils/__tests__/upload.test.ts | 11 +++++++++++ apps/web/src/utils/upload.ts | 4 ++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/apps/web/src/utils/__tests__/upload.test.ts b/apps/web/src/utils/__tests__/upload.test.ts index 3b3301ef1..9113d3da1 100644 --- a/apps/web/src/utils/__tests__/upload.test.ts +++ b/apps/web/src/utils/__tests__/upload.test.ts @@ -1549,4 +1549,15 @@ describe('reformatInstrumentData', () => { username: undefined }); }); + + it('should leave a name hash unscoped, so its records join the existing subject rather than a duplicate', () => { + const nameHash = '520be817915752b50f418a743a54b692ce8e2a0a3421931598ffad246182568f'; + expect( + reformatInstrumentData({ + currentGroup: group, + data: [{ ...data[0], subjectID: nameHash }], + instrument: unilingualFormInstrument.instance + }).records + ).toMatchObject([{ subjectId: nameHash }]); + }); }); diff --git a/apps/web/src/utils/upload.ts b/apps/web/src/utils/upload.ts index 766869dbe..0413140bd 100644 --- a/apps/web/src/utils/upload.ts +++ b/apps/web/src/utils/upload.ts @@ -6,7 +6,7 @@ import type { AnyUnilingualFormInstrument, FormTypes, Json } from '@opendatacapt import type { Group } from '@opendatacapture/schemas/group'; import type { UnilingualInstrumentInfo } from '@opendatacapture/schemas/instrument'; import type { UploadInstrumentRecordsData } from '@opendatacapture/schemas/instrument-records'; -import { encodeScopedSubjectId } from '@opendatacapture/subject-utils'; +import { toStoredSubjectId } from '@opendatacapture/subject-utils'; import { mapValues } from 'lodash-es'; import { parse, unparse } from 'papaparse'; import type { Merge } from 'type-fest'; @@ -1302,7 +1302,7 @@ export function reformatInstrumentData({ const createdRecord = { data: restOfData as Json, date: dataDate as Date, - subjectId: encodeScopedSubjectId(dataSubjectId as string, { + subjectId: toStoredSubjectId(dataSubjectId as string, { groupName: currentGroup?.name ?? 'root' }) }; From 168938b670accea017bb73e3faf438ebdae44402 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:49:40 -0500 Subject: [PATCH 11/19] feat(web): split the settings page into tabs and fold the mail server into it `/admin/settings` now has Features, Interface and Mail tabs. Features holds a Remote Assignments section (default validity and the remote assignments switch) and an Uploader section; Interface holds coloured table text, the group switcher position and the languages; Mail holds the mail server settings that had their own page. Features and Interface still save each change as it is made, and Mail still saves through its own buttons. No section is called "Settings" any more. Tabs, sections and the settings within them are ordered by their translated label, as the language list already was, and the first tab is the default. The chosen tab is held in the address as `?tab=`, so a reload or a shared link reopens it. Every tab stays mounted while hidden, so a mail form not yet saved survives a look at another tab. `/admin/mail` is removed with no redirect, and the sidebar's Instance group keeps only Settings and Branding. Co-Authored-By: Claude Opus 5.5 --- .agents/docs/playbooks/add-web-route.md | 2 +- .../ApplicationSettings.tsx | 68 +++ .../DefaultAssignmentDurationInput.tsx | 87 ++++ .../ApplicationSettings/FeaturesTab.tsx | 90 ++++ .../ApplicationSettings/InterfaceTab.tsx | 125 ++++++ .../ApplicationSettings/MailTab.tsx | 18 + .../ApplicationSettings/SettingsCard.tsx | 92 ++++ .../__tests__/ApplicationSettings.test.tsx | 172 ++++++++ .../DefaultAssignmentDurationInput.test.tsx | 156 +++++++ .../__tests__/FeaturesTab.test.tsx | 103 +++++ .../__tests__/InterfaceTab.test.tsx | 147 +++++++ .../__tests__/MailTab.test.tsx | 48 +++ .../__tests__/SettingsCard.test.tsx | 55 +++ .../__tests__/tabs.test.ts | 36 ++ .../components/ApplicationSettings/index.ts | 2 + .../components/ApplicationSettings/tabs.ts | 46 ++ .../components/ApplicationSettings/types.ts | 26 ++ .../src/hooks/__tests__/useNavItems.test.ts | 7 +- apps/web/src/hooks/useNavItems.ts | 5 - .../hooks/useUpdateMailSettingsMutation.ts | 2 +- .../routes/_app/admin/__tests__/mail.test.tsx | 82 ---- .../_app/admin/__tests__/settings.test.tsx | 393 +++--------------- apps/web/src/routes/_app/admin/mail.tsx | 36 -- apps/web/src/routes/_app/admin/settings.tsx | 366 +--------------- .../src/routes/_app/admin/users/create.tsx | 2 +- .../src/utils/__tests__/sort-by-label.test.ts | 25 ++ apps/web/src/utils/sort-by-label.ts | 7 + docs/en/3-guides/3.3-how-to-upload-data.mdx | 4 +- .../3.4-how-to-get-started-with-odc.mdx | 2 +- .../3.5-how-to-configure-permissions.mdx | 28 +- testing/src/pages/_app/admin/mail.page.ts | 61 --- testing/src/pages/_app/admin/settings.page.ts | 80 +++- testing/src/specs/authorization.spec.ts | 4 +- testing/src/specs/mail.spec.ts | 46 +- testing/src/support/fixtures.ts | 2 - 35 files changed, 1491 insertions(+), 934 deletions(-) create mode 100644 apps/web/src/components/ApplicationSettings/ApplicationSettings.tsx create mode 100644 apps/web/src/components/ApplicationSettings/DefaultAssignmentDurationInput.tsx create mode 100644 apps/web/src/components/ApplicationSettings/FeaturesTab.tsx create mode 100644 apps/web/src/components/ApplicationSettings/InterfaceTab.tsx create mode 100644 apps/web/src/components/ApplicationSettings/MailTab.tsx create mode 100644 apps/web/src/components/ApplicationSettings/SettingsCard.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/DefaultAssignmentDurationInput.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/FeaturesTab.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/InterfaceTab.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/MailTab.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/SettingsCard.test.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/tabs.test.ts create mode 100644 apps/web/src/components/ApplicationSettings/index.ts create mode 100644 apps/web/src/components/ApplicationSettings/tabs.ts create mode 100644 apps/web/src/components/ApplicationSettings/types.ts delete mode 100644 apps/web/src/routes/_app/admin/__tests__/mail.test.tsx delete mode 100644 apps/web/src/routes/_app/admin/mail.tsx create mode 100644 apps/web/src/utils/__tests__/sort-by-label.test.ts create mode 100644 apps/web/src/utils/sort-by-label.ts delete mode 100644 testing/src/pages/_app/admin/mail.page.ts diff --git a/.agents/docs/playbooks/add-web-route.md b/.agents/docs/playbooks/add-web-route.md index be20ac826..778f886ec 100644 --- a/.agents/docs/playbooks/add-web-route.md +++ b/.agents/docs/playbooks/add-web-route.md @@ -60,7 +60,7 @@ run the generator. it first. 10. **Add the tests.** A unit test named after the route file, in a `__tests__/` folder beside it - (`routes/_app/admin/__tests__/mail.test.tsx` tests `routes/_app/admin/mail.tsx`), and an e2e test + (`routes/_app/admin/__tests__/settings.test.tsx` tests `routes/_app/admin/settings.tsx`), and an e2e test — `.agents/docs/playbooks/add-e2e-test.md`. ## Verify diff --git a/apps/web/src/components/ApplicationSettings/ApplicationSettings.tsx b/apps/web/src/components/ApplicationSettings/ApplicationSettings.tsx new file mode 100644 index 000000000..237348aed --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/ApplicationSettings.tsx @@ -0,0 +1,68 @@ +import { useCallback, useRef, useState } from 'react'; + +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; + +import { SaveStatus } from '@/components/SaveStatus'; +import { SectionTabs } from '@/components/SectionTabs'; +import { useUpdateSetupStateMutation } from '@/hooks/useUpdateSetupStateMutation'; +import { sortByLabel } from '@/utils/sort-by-label'; + +import { SETTINGS_TABS } from './tabs'; + +import type { SettingsTabValue } from './tabs'; +import type { AutosaveSetupState } from './types'; + +const useSetupStateAutosave = () => { + // A failed autosave belongs beside the control the admin changed, not on the router error boundary. + const { mutate } = useUpdateSetupStateMutation({ throwOnError: false }); + const [saveState, setSaveState] = useState<'error' | 'idle' | 'saved' | 'saving'>('idle'); + const savedTimerRef = useRef>(undefined); + + // `mutate` is referentially stable across renders, so callbacks that depend on `autosave` stay stable too. + // A failed save leaves its status showing rather than clearing on a timer: the controls all render + // from server state, so once the pill is gone nothing else tells the admin their change never landed. + const autosave: AutosaveSetupState = useCallback( + (data) => { + clearTimeout(savedTimerRef.current); + setSaveState('saving'); + mutate(data, { + onError: () => setSaveState('error'), + onSuccess: () => { + setSaveState('saved'); + savedTimerRef.current = setTimeout(() => setSaveState('idle'), 2000); + } + }); + }, + [mutate] + ); + + return { autosave, saveState }; +}; + +type ApplicationSettingsProps = { + onTabChange: (tab: SettingsTabValue) => void; + /** Absent for the default tab, which is the first in label order. */ + tab: SettingsTabValue | undefined; +}; + +export const ApplicationSettings = ({ onTabChange, tab }: ApplicationSettingsProps) => { + const { t } = useTranslation(); + const { autosave, saveState } = useSetupStateAutosave(); + + const tabs = sortByLabel(SETTINGS_TABS.map((entry) => ({ ...entry, label: t(entry.label) }))); + // With no seed, `reduce` returns the first tab typed as present, which `tabs[0]` is not. + const selectedTab = tab ?? tabs.reduce((first) => first).value; + + return ( +
+ + {/* Every tab stays mounted, so a form not yet saved in one survives a look at another. */} + {tabs.map((entry) => ( + + ))} + +
+ ); +}; diff --git a/apps/web/src/components/ApplicationSettings/DefaultAssignmentDurationInput.tsx b/apps/web/src/components/ApplicationSettings/DefaultAssignmentDurationInput.tsx new file mode 100644 index 000000000..48fdc5b62 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/DefaultAssignmentDurationInput.tsx @@ -0,0 +1,87 @@ +import { useCallback, useEffect, useRef, useState } from 'react'; +import type React from 'react'; + +import { Input } from '@douglasneuroinformatics/libui/components'; +import { DEFAULT_ASSIGNMENT_DURATION_DAYS } from '@opendatacapture/schemas/assignment'; +import { MAX_ASSIGNMENT_DURATION_DAYS } from '@opendatacapture/schemas/setup'; + +import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; +import { parseDurationDays } from '@/utils/assignment-duration'; + +import type { AutosaveSetupState } from './types'; + +const DURATION_AUTOSAVE_DELAY = 700; + +type DefaultAssignmentDurationInputProps = { + autosave: AutosaveSetupState; +}; + +export const DefaultAssignmentDurationInput = ({ autosave }: DefaultAssignmentDurationInputProps) => { + const setupStateQuery = useSetupStateQuery(); + + // The input holds its own draft while the admin types. The saved draft is committed after a brief pause, + // on blur, and on unmount — so navigating away (e.g. clicking a sidebar link) still persists the value. + // It is resynced whenever the server value changes underneath (a save invalidates and refetches). + const savedDurationDays = setupStateQuery.data.defaultAssignmentDurationDays ?? DEFAULT_ASSIGNMENT_DURATION_DAYS; + const [durationDays, setDurationDays] = useState(String(savedDurationDays)); + const [syncedDurationDays, setSyncedDurationDays] = useState(savedDurationDays); + if (syncedDurationDays !== savedDurationDays) { + setSyncedDurationDays(savedDurationDays); + setDurationDays(String(savedDurationDays)); + } + + const durationDebounceRef = useRef>(undefined); + const durationDraftRef = useRef(durationDays); + durationDraftRef.current = durationDays; + const savedDurationRef = useRef(savedDurationDays); + savedDurationRef.current = savedDurationDays; + + const saveDurationIfChanged = useCallback(() => { + const parsed = parseDurationDays(durationDraftRef.current); + if (parsed !== null && parsed !== savedDurationRef.current) { + autosave({ defaultAssignmentDurationDays: parsed }); + } + return parsed; + }, [autosave]); + + const handleDurationBlur = (event: React.FocusEvent) => { + clearTimeout(durationDebounceRef.current); + const parsed = parseDurationDays(event.target.value); + if (parsed !== null && parsed !== savedDurationRef.current) { + setDurationDays(String(parsed)); + autosave({ defaultAssignmentDurationDays: parsed }); + } else if (parsed === null) { + setDurationDays(String(savedDurationRef.current)); + } + }; + + useEffect(() => { + return () => { + clearTimeout(durationDebounceRef.current); + saveDurationIfChanged(); + }; + }, [saveDurationIfChanged]); + + return ( + { + setDurationDays(event.target.value); + clearTimeout(durationDebounceRef.current); + durationDebounceRef.current = setTimeout(saveDurationIfChanged, DURATION_AUTOSAVE_DELAY); + }} + onKeyDown={(event) => { + if (event.key === 'Enter') { + event.currentTarget.blur(); + } + }} + /> + ); +}; diff --git a/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx b/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx new file mode 100644 index 000000000..488c42d02 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx @@ -0,0 +1,90 @@ +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; + +import { config } from '@/config'; +import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; + +import { DefaultAssignmentDurationInput } from './DefaultAssignmentDurationInput'; +import { SettingRows, SettingsCard, SettingToggle } from './SettingsCard'; + +import type { AutosaveSetupState } from './types'; + +type FeaturesTabProps = { + autosave: AutosaveSetupState; +}; + +export const FeaturesTab = ({ autosave }: FeaturesTabProps) => { + const { t } = useTranslation(); + const { data: setupState } = useSetupStateQuery(); + + const uploaderLabel = t({ en: 'Enable Uploader', es: 'Activar la carga de datos', fr: 'Activer le téléversement' }); + const uploaderSection = { + content: ( + autosave({ isExperimentalFeaturesEnabled: checked })} + /> + ), + help: t({ + en: 'When enabled, an upload menu item appears in the sidebar that allows users to upload instrument records directly from data files, bypassing the normal session workflow.', + es: 'Cuando está activada, aparece un elemento de menú de carga en la barra lateral que permite a los usuarios cargar registros de instrumentos directamente desde archivos de datos, sin pasar por el flujo de trabajo habitual de las sesiones.', + fr: "Lorsqu'elle est activée, un élément de menu Téléversement apparaît dans le menu latéral et permet aux utilisateurs de téléverser des enregistrements d'instruments directement à partir de fichiers de données." + }), + label: uploaderLabel + } + ]} + /> + ), + label: t({ en: 'Uploader', es: 'Carga de datos', fr: 'Téléversement' }) + }; + + const remoteAssignmentsLabel = t({ + en: 'Enable Remote Assignments', + es: 'Activar las tareas remotas', + fr: 'Activer les tâches à distance' + }); + const remoteAssignmentsRow = { + control: ( + autosave({ isBulkRemoteAssignmentsEnabled: checked })} + /> + ), + help: t({ + en: 'When enabled, the group links are collected under a Group Actions menu with an added page for assigning one or more instruments to many subjects at once. When disabled, those links stay where they are.', + es: 'Cuando está activada, los enlaces del grupo se reúnen bajo un menú Acciones del grupo con una página adicional para asignar uno o varios instrumentos a muchos sujetos a la vez. Cuando está desactivada, esos enlaces permanecen donde están.', + fr: 'Lorsqu’elle est activée, les liens de groupe sont regroupés sous un menu Actions de groupe avec une page permettant d’attribuer un ou plusieurs instruments à plusieurs sujets à la fois. Lorsqu’elle est désactivée, ces liens restent inchangés.' + }), + label: remoteAssignmentsLabel + }; + const durationRow = { + control: , + help: t({ + en: 'The number of days a new remote assignment stays valid by default. This only sets the initial expiry date when creating an assignment, which can still be changed for each one.', + es: 'El número de días que una nueva tarea remota permanece válida de forma predeterminada. Esto solo define la fecha de vencimiento inicial al crear una tarea, que se puede cambiar en cada caso.', + fr: "Le nombre de jours pendant lesquels une nouvelle tâche à distance reste valide par défaut. Ceci ne définit que la date d'expiration initiale lors de la création d'une tâche, qui peut toujours être modifiée pour chacune." + }), + label: t({ + en: 'Default Assignment Validity (Days)', + es: 'Validez predeterminada de las tareas (días)', + fr: 'Validité par défaut des tâches (jours)' + }) + }; + const remoteAssignmentsSection = { + content: ( + + ), + label: t({ en: 'Remote Assignments', es: 'Tareas remotas', fr: 'Tâches à distance' }) + }; + + return ; +}; diff --git a/apps/web/src/components/ApplicationSettings/InterfaceTab.tsx b/apps/web/src/components/ApplicationSettings/InterfaceTab.tsx new file mode 100644 index 000000000..0482bd6b6 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/InterfaceTab.tsx @@ -0,0 +1,125 @@ +import React from 'react'; + +import { Checkbox, Select } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { Language } from '@opendatacapture/schemas/core'; + +import { SelectTableColorMode } from '@/components/SelectTableColorMode'; +import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; +import { useAppStore } from '@/store'; +import type { GroupSwitcherPosition } from '@/store/types'; +import { LANGUAGE_LABELS, LANGUAGES } from '@/utils/language'; +import { sortByLabel } from '@/utils/sort-by-label'; + +import { SettingsCard } from './SettingsCard'; + +import type { AutosaveSetupState } from './types'; + +type InterfaceTabProps = { + autosave: AutosaveSetupState; +}; + +export const InterfaceTab = ({ autosave }: InterfaceTabProps) => { + const { t } = useTranslation(); + const { data: setupState } = useSetupStateQuery(); + const groupSwitcherPosition = useAppStore((store) => store.groupSwitcherPosition); + const setGroupSwitcherPosition = useAppStore((store) => store.setGroupSwitcherPosition); + + const { activeLanguages } = setupState; + + // Rebuilt by filtering LANGUAGES rather than appending, so the stored order is always the + // canonical one — the first entry is what a user stranded by a deactivation falls back to, + // and it must not depend on the order an admin happened to click. + const toggleLanguage = (language: Language) => { + const updated = LANGUAGES.filter((code) => { + return code === language ? !activeLanguages.includes(code) : activeLanguages.includes(code); + }); + const [first, ...rest] = updated; + if (!first) { + return; + } + autosave({ activeLanguages: [first, ...rest] }); + }; + + return ( + autosave({ tableColorMode })} + /> + ), + label: t({ + en: 'Coloured Text In Tables', + es: 'Texto de color en las tablas', + fr: 'Texte coloré dans les tableaux' + }) + }, + { + content: ( + + ), + label: t({ + en: 'Group Switcher Position', + es: 'Posición del selector de grupo', + fr: 'Position du sélecteur de groupe' + }) + }, + { + content: ( + +

+ {t({ + en: 'The languages users of this instance can read the interface in.', + es: 'Los idiomas en los que los usuarios de esta instancia pueden leer la interfaz.', + fr: "Les langues dans lesquelles les utilisateurs de cette instance peuvent lire l'interface." + })} +

+
+ {sortByLabel(LANGUAGES.map((language) => ({ label: t(LANGUAGE_LABELS[language]), language }))).map( + ({ label, language }) => { + const isActive = activeLanguages.includes(language); + return ( +
+ toggleLanguage(language)} + /> + +
+ ); + } + )} +
+
+ ), + label: t({ en: 'Languages', es: 'Idiomas', fr: 'Langues' }) + } + ]} + /> + ); +}; diff --git a/apps/web/src/components/ApplicationSettings/MailTab.tsx b/apps/web/src/components/ApplicationSettings/MailTab.tsx new file mode 100644 index 000000000..fb4a9b96a --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/MailTab.tsx @@ -0,0 +1,18 @@ +import { MailSettings } from '@/components/MailSettings'; +import { useMailSettingsQuery } from '@/hooks/useMailSettingsQuery'; +import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; + +export const MailTab = () => { + const { data: settings } = useMailSettingsQuery(); + const { data: setupState } = useSetupStateQuery(); + + return ( +
+ +
+ ); +}; diff --git a/apps/web/src/components/ApplicationSettings/SettingsCard.tsx b/apps/web/src/components/ApplicationSettings/SettingsCard.tsx new file mode 100644 index 000000000..6742c8334 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/SettingsCard.tsx @@ -0,0 +1,92 @@ +import React from 'react'; + +import { Card, HoverCard, Separator } from '@douglasneuroinformatics/libui/components'; +import { cn } from '@douglasneuroinformatics/libui/utils'; +import { CircleHelpIcon } from 'lucide-react'; + +import { sortByLabel } from '@/utils/sort-by-label'; + +export type SettingsSection = { + content: React.ReactNode; + label: string; +}; + +export type SettingsCardProps = { + sections: readonly SettingsSection[]; +}; + +export const SettingsCard = ({ sections }: SettingsCardProps) => ( + + + {sortByLabel(sections).map(({ content, label }, index) => ( + + {index > 0 && } +
+

{label}

+ {content} +
+
+ ))} +
+
+); + +export type SettingRow = { + control: React.ReactNode; + help: string; + label: string; +}; + +export type SettingRowsProps = { + rows: readonly SettingRow[]; +}; + +export const SettingRows = ({ rows }: SettingRowsProps) => ( + + {sortByLabel(rows).map(({ control, help, label }) => ( +
+
+

{label}

+ + + + + {help} + +
+ {control} +
+ ))} +
+); + +export type SettingToggleProps = { + checked: boolean; + /** Names the switch for assistive technology. */ + label: string; + onCheckedChange: (checked: boolean) => void; +}; + +/** libui ships no Switch, so this is hand-rolled. */ +export const SettingToggle = ({ checked, label, onCheckedChange }: SettingToggleProps) => ( + +); diff --git a/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx b/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx new file mode 100644 index 000000000..3018b8f47 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx @@ -0,0 +1,172 @@ +import { i18n } from '@douglasneuroinformatics/libui/i18n'; +import type { $UpdateSetupStateData } from '@opendatacapture/schemas/setup'; +import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { ApplicationSettings } from '../ApplicationSettings'; + +import type { SettingsTabValue } from '../tabs'; +import type { AutosaveSetupState } from '../types'; + +import '@/services/i18n'; + +type MutateCallbacks = { onError: () => void; onSuccess: () => void }; + +const mocks = vi.hoisted(() => ({ + MailTab: vi.fn((_: object) =>
), + mutate: vi.fn<(data: $UpdateSetupStateData, callbacks: MutateCallbacks) => void>(), + useUpdateSetupStateMutation: vi.fn() +})); + +vi.mock('@/hooks/useUpdateSetupStateMutation', () => ({ + useUpdateSetupStateMutation: (options: unknown) => { + mocks.useUpdateSetupStateMutation(options); + return { mutate: mocks.mutate }; + } +})); +vi.mock('../FeaturesTab', () => ({ + FeaturesTab: ({ autosave }: { autosave: AutosaveSetupState }) => ( + -); - -const SettingSection = ({ children, title }: { children: React.ReactNode; title: string }) => ( -
-

{title}

- {children} -
-); - -const DURATION_AUTOSAVE_DELAY = 700; const RouteComponent = () => { const { t } = useTranslation(); - const setupStateQuery = useSetupStateQuery(); - const updateSetupStateMutation = useUpdateSetupStateMutation({ throwOnError: false }); - const groupSwitcherPosition = useAppStore((store) => store.groupSwitcherPosition); - const setGroupSwitcherPosition = useAppStore((store) => store.setGroupSwitcherPosition); - - // `mutate` is referentially stable across renders, so callbacks that depend on `autosave` stay stable too. - const { mutate } = updateSetupStateMutation; - const [saveState, setSaveState] = useState<'error' | 'idle' | 'saved' | 'saving'>('idle'); - const savedTimerRef = useRef>(undefined); - - // A failed save leaves its status showing rather than clearing on a timer: the controls all render - // from server state, so once the pill is gone nothing else tells the admin their change never landed. - const autosave = useCallback( - (data: Parameters[0]) => { - clearTimeout(savedTimerRef.current); - setSaveState('saving'); - mutate(data, { - onError: () => setSaveState('error'), - onSuccess: () => { - setSaveState('saved'); - savedTimerRef.current = setTimeout(() => setSaveState('idle'), 2000); - } - }); - }, - [mutate] - ); - - const uploaderLabel = t({ en: 'Enable Uploader', es: 'Activar la carga de datos', fr: 'Activer le téléversement' }); - const uploaderEnabled = setupStateQuery.data.isExperimentalFeaturesEnabled ?? false; - - const bulkLabel = t({ - en: 'Enable Remote Assignments', - es: 'Activar las tareas remotas', - fr: 'Activer les tâches à distance' - }); - const bulkEnabled = setupStateQuery.data.isBulkRemoteAssignmentsEnabled ?? true; - - const activeLanguages = setupStateQuery.data.activeLanguages; - - // Rebuilt by filtering LANGUAGES rather than appending, so the stored order is always the - // canonical one — the first entry is what a user stranded by a deactivation falls back to, - // and it must not depend on the order an admin happened to click. - const toggleLanguage = (language: Language) => { - const updated = LANGUAGES.filter((code) => { - return code === language ? !activeLanguages.includes(code) : activeLanguages.includes(code); - }); - const [first, ...rest] = updated; - if (!first) { - return; - } - autosave({ activeLanguages: [first, ...rest] }); - }; - - // The input holds its own draft while the admin types. The saved draft is committed after a brief pause, - // on blur, and on unmount — so navigating away (e.g. clicking a sidebar link) still persists the value. - // It is resynced whenever the server value changes underneath (a save invalidates and refetches). - const savedDurationDays = setupStateQuery.data.defaultAssignmentDurationDays ?? DEFAULT_ASSIGNMENT_DURATION_DAYS; - const [durationDays, setDurationDays] = useState(String(savedDurationDays)); - const [syncedDurationDays, setSyncedDurationDays] = useState(savedDurationDays); - if (syncedDurationDays !== savedDurationDays) { - setSyncedDurationDays(savedDurationDays); - setDurationDays(String(savedDurationDays)); - } - - const durationDebounceRef = useRef>(undefined); - const durationDraftRef = useRef(durationDays); - durationDraftRef.current = durationDays; - const savedDurationRef = useRef(savedDurationDays); - savedDurationRef.current = savedDurationDays; - - const saveDurationIfChanged = useCallback(() => { - const parsed = parseDurationDays(durationDraftRef.current); - if (parsed !== null && parsed !== savedDurationRef.current) { - autosave({ defaultAssignmentDurationDays: parsed }); - } - return parsed; - }, [autosave]); - - const handleDurationBlur = (event: React.FocusEvent) => { - clearTimeout(durationDebounceRef.current); - const parsed = parseDurationDays(event.target.value); - if (parsed !== null && parsed !== savedDurationRef.current) { - setDurationDays(String(parsed)); - autosave({ defaultAssignmentDurationDays: parsed }); - } else if (parsed === null) { - setDurationDays(String(savedDurationRef.current)); - } - }; - - useEffect(() => { - return () => { - clearTimeout(durationDebounceRef.current); - saveDurationIfChanged(); - }; - }, [saveDurationIfChanged]); + const { tab } = Route.useSearch(); + const navigate = Route.useNavigate(); return ( - +
{t({ @@ -176,202 +21,15 @@ const RouteComponent = () => { })} -
- - - -
-
-

{uploaderLabel}

- - - - - - {t({ - en: 'When enabled, an upload menu item appears in the sidebar that allows users to upload instrument records directly from data files, bypassing the normal session workflow.', - es: 'Cuando está activada, aparece un elemento de menú de carga en la barra lateral que permite a los usuarios cargar registros de instrumentos directamente desde archivos de datos, sin pasar por el flujo de trabajo habitual de las sesiones.', - fr: "Lorsqu'elle est activée, un élément de menu Téléversement apparaît dans le menu latéral et permet aux utilisateurs de téléverser des enregistrements d'instruments directement à partir de fichiers de données." - })} - - -
- autosave({ isExperimentalFeaturesEnabled: checked })} - /> -
-
-
-

{bulkLabel}

- - - - - - {t({ - en: 'When enabled, the group links are collected under a Group Actions menu with an added page for assigning one or more instruments to many subjects at once. When disabled, those links stay where they are.', - es: 'Cuando está activada, los enlaces del grupo se reúnen bajo un menú Acciones del grupo con una página adicional para asignar uno o varios instrumentos a muchos sujetos a la vez. Cuando está desactivada, esos enlaces permanecen donde están.', - fr: 'Lorsqu’elle est activée, les liens de groupe sont regroupés sous un menu Actions de groupe avec une page permettant d’attribuer un ou plusieurs instruments à plusieurs sujets à la fois. Lorsqu’elle est désactivée, ces liens restent inchangés.' - })} - - -
- autosave({ isBulkRemoteAssignmentsEnabled: checked })} - /> -
-
- {/* The only thing this section configures is the expiry of a remote assignment, which - an instance deployed without the gateway can never create */} - {config.setup.isGatewayEnabled && ( - - - -
-
-

- {t({ - en: 'Default Assignment Validity (Days)', - es: 'Validez predeterminada de las tareas (días)', - fr: 'Validité par défaut des tâches (jours)' - })} -

- - - - - - {t({ - en: 'The number of days a new remote assignment stays valid by default. This only sets the initial expiry date when creating an assignment, which can still be changed for each one.', - es: 'El número de días que una nueva tarea remota permanece válida de forma predeterminada. Esto solo define la fecha de vencimiento inicial al crear una tarea, que se puede cambiar en cada caso.', - fr: "Le nombre de jours pendant lesquels une nouvelle tâche à distance reste valide par défaut. Ceci ne définit que la date d'expiration initiale lors de la création d'une tâche, qui peut toujours être modifiée pour chacune." - })} - - -
- { - setDurationDays(event.target.value); - clearTimeout(durationDebounceRef.current); - durationDebounceRef.current = setTimeout(saveDurationIfChanged, DURATION_AUTOSAVE_DELAY); - }} - onKeyDown={(event) => { - if (event.key === 'Enter') { - event.currentTarget.blur(); - } - }} - /> -
-
-
- )} - - -
-

- {t({ - en: 'The languages users of this instance can read the interface in.', - es: 'Los idiomas en los que los usuarios de esta instancia pueden leer la interfaz.', - fr: "Les langues dans lesquelles les utilisateurs de cette instance peuvent lire l'interface." - })} -

-
-
- {[...LANGUAGES] - .sort((a, b) => t(LANGUAGE_LABELS[a]).localeCompare(t(LANGUAGE_LABELS[b]))) - .map((language) => { - const isActive = activeLanguages.includes(language); - return ( -
- toggleLanguage(language)} - /> - -
- ); - })} -
-
- - -
-

- {t({ - en: 'Group Switcher Position', - es: 'Posición del selector de grupo', - fr: 'Position du sélecteur de groupe' - })} -

- -
-
-

- {t({ - en: 'Coloured Text In Tables', - es: 'Texto de color en las tablas', - fr: 'Texte coloré dans les tableaux' - })} -

- autosave({ tableColorMode })} - /> -
-
-
-
-
- - + void navigate({ search: { tab: next }, to: '.' })} /> +
); }; export const Route = createFileRoute('/_app/admin/settings')({ - component: RouteComponent + component: RouteComponent, + loader: async ({ context }) => { + await Promise.all(SETTINGS_TABS.map(async (tab) => tab.prefetch?.(context.queryClient))); + }, + validateSearch: $ApplicationSettingsSearch }); diff --git a/apps/web/src/routes/_app/admin/users/create.tsx b/apps/web/src/routes/_app/admin/users/create.tsx index 8b62a4efc..e98aeed66 100644 --- a/apps/web/src/routes/_app/admin/users/create.tsx +++ b/apps/web/src/routes/_app/admin/users/create.tsx @@ -44,7 +44,7 @@ const RouteComponent = () => { const [fallbackMessage, setFallbackMessage] = React.useState(null); const [emailLanguageChoice, setEmailLanguageChoice] = React.useState(resolvedLanguage); // Clamp to what is offered: a language the instance has since disabled has no template on the - // mail page any more, and would leave the trigger blank while that language is still posted. + // mail settings any more, and would leave the trigger blank while that language is still posted. const activeLanguages = setupStateQuery.data.activeLanguages; const emailLanguage = activeLanguages.includes(emailLanguageChoice) ? emailLanguageChoice : activeLanguages[0]; diff --git a/apps/web/src/utils/__tests__/sort-by-label.test.ts b/apps/web/src/utils/__tests__/sort-by-label.test.ts new file mode 100644 index 000000000..ebe23b4cb --- /dev/null +++ b/apps/web/src/utils/__tests__/sort-by-label.test.ts @@ -0,0 +1,25 @@ +import { describe, expect, it } from 'vitest'; + +import { sortByLabel } from '../sort-by-label'; + +describe('sortByLabel', () => { + it('should order entries alphabetically by their label, not by the order they were written in', () => { + const entries = [{ label: 'Uploader' }, { label: 'Remote Assignments' }, { label: 'Interface' }]; + expect(sortByLabel(entries).map(({ label }) => label)).toStrictEqual([ + 'Interface', + 'Remote Assignments', + 'Uploader' + ]); + }); + + it('should place an accented letter beside its base letter, so French labels sort as a reader expects', () => { + const entries = [{ label: 'Téléversement' }, { label: 'Tâches à distance' }]; + expect(sortByLabel(entries).map(({ label }) => label)).toStrictEqual(['Tâches à distance', 'Téléversement']); + }); + + it('should leave the given list in its original order', () => { + const entries = [{ label: 'B' }, { label: 'A' }]; + sortByLabel(entries); + expect(entries.map(({ label }) => label)).toStrictEqual(['B', 'A']); + }); +}); diff --git a/apps/web/src/utils/sort-by-label.ts b/apps/web/src/utils/sort-by-label.ts new file mode 100644 index 000000000..3a53b5b4c --- /dev/null +++ b/apps/web/src/utils/sort-by-label.ts @@ -0,0 +1,7 @@ +/** + * Order entries alphabetically by the label a reader sees. Sorting the translated label rather than + * keeping the order the entries were written in is what keeps a list scannable in every language. + */ +export const sortByLabel = (entries: readonly TEntry[]): TEntry[] => { + return entries.toSorted((a, b) => a.label.localeCompare(b.label)); +}; diff --git a/docs/en/3-guides/3.3-how-to-upload-data.mdx b/docs/en/3-guides/3.3-how-to-upload-data.mdx index ac02a51f8..c658f1efc 100644 --- a/docs/en/3-guides/3.3-how-to-upload-data.mdx +++ b/docs/en/3-guides/3.3-how-to-upload-data.mdx @@ -9,7 +9,7 @@ import { Steps } from '@astrojs/starlight/components'; Open Data Capture can import records for a form instrument from a CSV file. Each row of the file becomes one record of that instrument for a subject in the currently selected group. -Upload is an experimental feature. The **Upload Data** item appears in the navigation only after an admin turns on **Enable Uploader** under **Admin Panel** > **App Settings**, and only for accounts that can read subjects and create instrument records. The default Group Manager and Standard User roles both have those permissions. +Upload is an experimental feature. The **Upload Data** item appears in the navigation only after an admin turns on **Enable Uploader** on the **Features** tab of **Admin Panel** > **Instance** > **Settings**, and only for accounts that can read subjects and create instrument records. The default Group Manager and Standard User roles both have those permissions. ### Steps @@ -17,7 +17,7 @@ Upload is an experimental feature. The **Upload Data** item appears in the navig 1. **Login to Open Data Capture** - First, login to your instance of Open Data Capture. If you do not see **Upload Data** in the navigation, ask an admin to turn on **Enable Uploader** under **Admin Panel** > **App Settings** and to check that your account can read subjects and create instrument records. + First, login to your instance of Open Data Capture. If you do not see **Upload Data** in the navigation, ask an admin to turn on **Enable Uploader** on the **Features** tab of **Admin Panel** > **Instance** > **Settings** and to check that your account can read subjects and create instrument records. 2. **Select Your Group** diff --git a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx index fe452146c..bdf7a3dd9 100644 --- a/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx +++ b/docs/en/3-guides/3.4-how-to-get-started-with-odc.mdx @@ -138,7 +138,7 @@ The **Download** menu on Data Hub's Subjects page downloads the records of the l Use **Upload Data** to import CSV data for form instruments. -Upload Data appears when the instance admin has enabled experimental features (**Enable Uploader** in App Settings) and your account can read subjects and create instrument records. The default Group Manager and Standard User roles satisfy those permissions. +Upload Data appears when the instance admin has enabled experimental features (**Enable Uploader** on the **Features** tab of **Admin Panel** > **Instance** > **Settings**) and your account can read subjects and create instrument records. The default Group Manager and Standard User roles satisfy those permissions. For more detail, see [How to Upload Data](/en/docs/guides/how-to-upload-data/). diff --git a/docs/en/3-guides/3.5-how-to-configure-permissions.mdx b/docs/en/3-guides/3.5-how-to-configure-permissions.mdx index bc2b6fe8d..7dd0e699c 100644 --- a/docs/en/3-guides/3.5-how-to-configure-permissions.mdx +++ b/docs/en/3-guides/3.5-how-to-configure-permissions.mdx @@ -81,20 +81,20 @@ Use a permission set when several users need the same additional permissions. Ed Each item appears in the navigation only when the user has the permissions in **Shown with** and meets the conditions in **Shown only with**. The navigation checks no more than that, but the page behind the item loads its own data, and using it also takes the permissions in **Page also needs**. Read Group there means the group selected in the group switcher, and is needed only while one is selected. -| Item | Shown with | Shown only with | Page also needs | -| ------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | -| **Dashboard** | Read Instrument, Read Instrument Record, Read Subject and Read User | | Read Session, without which the item opens **Start Session** instead, and Read Group | -| **Data Hub** > **Subjects** | Read Subject and Read Instrument Record | | See [Data Hub](#data-hub) | -| **Data Hub** > **Instruments** | Read Subject, Read Instrument Record and Read Instrument | | See [Data Hub](#data-hub) | -| **Upload Data** | Read Subject and Create Instrument Record | **Enable Uploader** under **Admin Panel** > **Instance** > **Settings** | Read Instrument, Read User and Read Group | -| **Manage Group** | Manage (All) on Group | A group selected in the group switcher | Read Instrument, and Create or Delete Instrument to create or delete a series | -| **Email Templates** | Manage (All) on Group | A configured mail server, gateway support, and a group selected | | -| **Remote Assignments** (create and delete) | Create Assignment, Read Assignment and Read Subject | **Enable Remote Assignments** under **Admin Panel** > **Instance** > **Settings**, gateway support, and a group selected | Read Instrument, plus Read Group to create, Delete Assignment to delete, and Update Assignment to email the links | -| **Admin Panel** | Manage (All) on All, which only admins hold | | | -| **Start Session** | Create Session | | Read Subject, Read User and Read Group | -| **Administer Instrument** | Create Instrument Record | An active session | Read Instrument and Read Group, and a base permission level for a file instrument | -| **Remote Assignment** | Create Assignment | Gateway support and an active session | Read Instrument, Read Subject and Read Group, plus Read Assignment and Update Assignment to email the link | -| **View Current Subject** | Read Subject and Read Instrument Record | An active session | Read Instrument and Read Session | +| Item | Shown with | Shown only with | Page also needs | +| ------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **Dashboard** | Read Instrument, Read Instrument Record, Read Subject and Read User | | Read Session, without which the item opens **Start Session** instead, and Read Group | +| **Data Hub** > **Subjects** | Read Subject and Read Instrument Record | | See [Data Hub](#data-hub) | +| **Data Hub** > **Instruments** | Read Subject, Read Instrument Record and Read Instrument | | See [Data Hub](#data-hub) | +| **Upload Data** | Read Subject and Create Instrument Record | **Enable Uploader** under **Admin Panel** > **Instance** > **Settings** > **Features** | Read Instrument, Read User and Read Group | +| **Manage Group** | Manage (All) on Group | A group selected in the group switcher | Read Instrument, and Create or Delete Instrument to create or delete a series | +| **Email Templates** | Manage (All) on Group | A configured mail server, gateway support, and a group selected | | +| **Remote Assignments** (create and delete) | Create Assignment, Read Assignment and Read Subject | **Enable Remote Assignments** under **Admin Panel** > **Instance** > **Settings** > **Features**, gateway support, and a group selected | Read Instrument, plus Read Group to create, Delete Assignment to delete, and Update Assignment to email the links | +| **Admin Panel** | Manage (All) on All, which only admins hold | | | +| **Start Session** | Create Session | | Read Subject, Read User and Read Group | +| **Administer Instrument** | Create Instrument Record | An active session | Read Instrument and Read Group, and a base permission level for a file instrument | +| **Remote Assignment** | Create Assignment | Gateway support and an active session | Read Instrument, Read Subject and Read Group, plus Read Assignment and Update Assignment to email the link | +| **View Current Subject** | Read Subject and Read Instrument Record | An active session | Read Instrument and Read Session | ### Data Hub diff --git a/testing/src/pages/_app/admin/mail.page.ts b/testing/src/pages/_app/admin/mail.page.ts deleted file mode 100644 index 77898cb07..000000000 --- a/testing/src/pages/_app/admin/mail.page.ts +++ /dev/null @@ -1,61 +0,0 @@ -import type { Locator, Page } from '@playwright/test'; - -import { AppPage } from '../route.page'; - -export class MailSettingsPage extends AppPage { - readonly enableToggle: Locator; - readonly host: Locator; - readonly password: Locator; - readonly port: Locator; - readonly saveConfig: Locator; - readonly senderAddress: Locator; - readonly serverCard: Locator; - readonly testConnection: Locator; - readonly username: Locator; - - constructor(page: Page) { - super(page); - this.enableToggle = page.getByTestId('mail-enabled-toggle'); - this.serverCard = page.getByTestId('mail-server-card'); - this.host = page.getByTestId('mail-host'); - this.port = page.getByTestId('mail-port'); - this.username = page.getByTestId('mail-username'); - this.password = page.getByTestId('mail-password'); - this.senderAddress = page.getByTestId('mail-sender-address'); - this.saveConfig = page.getByTestId('mail-save-config'); - this.testConnection = page.getByTestId('mail-test-connection'); - } - - /** Idempotent: a configuration left enabled by an earlier spec already shows the form. */ - async enableMail() { - // Branch on the toggle's own state, not the card's visibility. `isVisible` is a point-in-time - // check with no auto-waiting, so on a slow first paint it reports false for an instance where - // mail is already on — and the click that follows then turns mail OFF for the whole instance, - // which breaks this spec and any other running against a mail-enabled instance. - await this.enableToggle.waitFor({ state: 'visible' }); - if (!(await this.enableToggle.isChecked())) { - await this.enableToggle.click(); - } - await this.serverCard.waitFor({ state: 'visible' }); - } - - async fillServerConfig({ - host, - password, - port, - senderAddress, - username - }: { - host: string; - password: string; - port: string; - senderAddress: string; - username: string; - }) { - await this.host.fill(host); - await this.port.fill(port); - await this.username.fill(username); - await this.password.fill(password); - await this.senderAddress.fill(senderAddress); - } -} diff --git a/testing/src/pages/_app/admin/settings.page.ts b/testing/src/pages/_app/admin/settings.page.ts index e108eaf81..cbbdd0815 100644 --- a/testing/src/pages/_app/admin/settings.page.ts +++ b/testing/src/pages/_app/admin/settings.page.ts @@ -1,9 +1,21 @@ -import type { Locator, Page } from '@playwright/test'; +import { expect } from '@playwright/test'; +import type { Locator, Page, Response } from '@playwright/test'; import { AppPage } from '../route.page'; +type SettingsTab = 'features' | 'interface' | 'mail'; + export class AdminSettingsPage extends AppPage { readonly defaultAssignmentDurationInput: Locator; + readonly mailEnableToggle: Locator; + readonly mailHost: Locator; + readonly mailPassword: Locator; + readonly mailPort: Locator; + readonly mailSaveConfig: Locator; + readonly mailSenderAddress: Locator; + readonly mailServerCard: Locator; + readonly mailTestConnection: Locator; + readonly mailUsername: Locator; readonly pageHeader: Locator; readonly uploaderToggle: Locator; @@ -12,10 +24,76 @@ export class AdminSettingsPage extends AppPage { this.pageHeader = page.getByTestId('page-header'); this.uploaderToggle = page.getByRole('switch', { name: 'Enable Uploader' }); this.defaultAssignmentDurationInput = page.getByTestId('default-assignment-duration-input'); + this.mailEnableToggle = page.getByTestId('mail-enabled-toggle'); + this.mailServerCard = page.getByTestId('mail-server-card'); + this.mailHost = page.getByTestId('mail-host'); + this.mailPort = page.getByTestId('mail-port'); + this.mailUsername = page.getByTestId('mail-username'); + this.mailPassword = page.getByTestId('mail-password'); + this.mailSenderAddress = page.getByTestId('mail-sender-address'); + this.mailSaveConfig = page.getByTestId('mail-save-config'); + this.mailTestConnection = page.getByTestId('mail-test-connection'); + } + + /** + * Idempotent: a configuration left enabled by an earlier spec already shows the form. Needs a + * stored configuration, which `api.setMailEnabled` always leaves. + */ + async enableMail() { + // Branch on the toggle's own state, not the card's visibility. `isVisible` is a point-in-time + // check with no auto-waiting, so on a slow first paint it reports false for an instance where + // mail is already on — and the click that follows then turns mail OFF for the whole instance, + // which breaks this spec and any other running against a mail-enabled instance. + await this.mailEnableToggle.waitFor({ state: 'visible' }); + if (!(await this.mailEnableToggle.isChecked())) { + // Turning mail on saves the stored configuration at once, and the form then reloads from the + // saved copy, which would overwrite anything typed before that save returns. + const saved = this.waitForMailSave(); + await this.mailEnableToggle.click(); + await saved; + } + await this.mailServerCard.waitFor({ state: 'visible' }); + } + + async fillMailServerConfig({ + host, + password, + port, + senderAddress, + username + }: { + host: string; + password: string; + port: string; + senderAddress: string; + username: string; + }) { + await this.mailHost.fill(host); + await this.mailPort.fill(port); + await this.mailUsername.fill(username); + await this.mailPassword.fill(password); + await this.mailSenderAddress.fill(senderAddress); + } + + /** Every tab stays in the page, hidden until chosen, so its controls are not visible before this. */ + async openTab(tab: SettingsTab) { + await this.$ref.getByTestId(`settings-tab-${tab}`).click(); + await expect(this.tabPanel(tab)).toBeVisible(); } async setDefaultAssignmentDuration(days: number) { await this.defaultAssignmentDurationInput.fill(String(days)); await this.defaultAssignmentDurationInput.press('Enter'); } + + tabPanel(tab: SettingsTab): Locator { + return this.$ref.getByTestId(`settings-panel-${tab}`); + } + + // The enable toggle and the save button send the same request, so this matches whichever saves next. + waitForMailSave(): Promise { + return this.$ref.waitForResponse( + (response) => response.url().endsWith('/v1/mail/settings') && response.request().method() === 'PATCH' + ); + } } diff --git a/testing/src/specs/authorization.spec.ts b/testing/src/specs/authorization.spec.ts index c64889c1e..68282fd61 100644 --- a/testing/src/specs/authorization.spec.ts +++ b/testing/src/specs/authorization.spec.ts @@ -27,9 +27,7 @@ const ADMIN_ONLY_ROUTES = [ '/admin/settings', '/admin/branding', '/admin/instrument-repos', - '/admin/audit/logs', - // Only asserted negatively (hidden from non-admins), which holds whether or not mail is on. - '/admin/mail' + '/admin/audit/logs' ] as const; /** Routes with no role gating at all -- reachable by every authenticated role. */ diff --git a/testing/src/specs/mail.spec.ts b/testing/src/specs/mail.spec.ts index 19947c096..38b276bb5 100644 --- a/testing/src/specs/mail.spec.ts +++ b/testing/src/specs/mail.spec.ts @@ -24,9 +24,10 @@ test.describe('mail settings', () => { // The whole save path — validate, persist, re-seed from the response — while the secret // itself never round-trips back to the browser. test('should save a valid configuration without ever rendering the stored password', async ({ getPageModel }) => { - const mailPage = await getPageModel('/admin/mail'); - await mailPage.enableMail(); - await mailPage.fillServerConfig({ + const settingsPage = await getPageModel('/admin/settings'); + await settingsPage.openTab('mail'); + await settingsPage.enableMail(); + await settingsPage.fillMailServerConfig({ host: 'smtp.saved.test', password: 'hunter2', port: '2525', @@ -34,18 +35,22 @@ test.describe('mail settings', () => { username: 'saver' }); - await mailPage.saveConfig.click(); - await expect(mailPage.$ref.getByRole('heading', { name: 'Success' }).last()).toBeVisible(); - - // The reload proves the save reached the database, not merely component state. - await mailPage.$ref.reload(); - await mailPage.enableMail(); - await expect(mailPage.host).toHaveValue('smtp.saved.test'); - await expect(mailPage.username).toHaveValue('saver'); - await expect(mailPage.port).toHaveValue('2525'); - await expect(mailPage.password).toHaveAttribute('type', 'password'); - await expect(mailPage.password).not.toHaveValue('hunter2'); - await expect(mailPage.$ref.locator('body')).not.toContainText('hunter2'); + // Turning mail on raised a success notification of its own, so only the response says this save landed. + const saved = settingsPage.waitForMailSave(); + await settingsPage.mailSaveConfig.click(); + expect((await saved).ok()).toBe(true); + + // The reload proves the save reached the database, not merely component state. It reopens the + // mail tab without a click, because the chosen tab is held in the address. + await settingsPage.$ref.reload(); + await expect(settingsPage.tabPanel('mail')).toBeVisible(); + await settingsPage.enableMail(); + await expect(settingsPage.mailHost).toHaveValue('smtp.saved.test'); + await expect(settingsPage.mailUsername).toHaveValue('saver'); + await expect(settingsPage.mailPort).toHaveValue('2525'); + await expect(settingsPage.mailPassword).toHaveAttribute('type', 'password'); + await expect(settingsPage.mailPassword).not.toHaveValue('hunter2'); + await expect(settingsPage.$ref.locator('body')).not.toContainText('hunter2'); }); }); @@ -58,21 +63,22 @@ test.describe('mail delivery', () => { await api.setMailEnabled(false); }); - test.describe('admin mail page', () => { + test.describe('admin mail settings', () => { test.use({ actingRole: 'ADMIN' }); test('should report a failed connection test in the reader’s language, not raw SMTP prose', async ({ getPageModel }) => { - const mailPage = await getPageModel('/admin/mail'); + const settingsPage = await getPageModel('/admin/settings'); + await settingsPage.openTab('mail'); - await mailPage.testConnection.click(); + await settingsPage.mailTestConnection.click(); // `smtp.invalid.test` cannot resolve, so this exercises the whole failure path: nodemailer // error -> MailErrorCode -> localized copy. A raw driver message would leak "ENOTFOUND". - const notification = mailPage.$ref.getByText(/could not be found|check and reconfigure/i); + const notification = settingsPage.$ref.getByText(/could not be found|check and reconfigure/i); await expect(notification.first()).toBeVisible({ timeout: 40_000 }); - await expect(mailPage.$ref.locator('body')).not.toContainText('ENOTFOUND'); + await expect(settingsPage.$ref.locator('body')).not.toContainText('ENOTFOUND'); }); }); diff --git a/testing/src/support/fixtures.ts b/testing/src/support/fixtures.ts index f941e8ecc..9b1971e9c 100644 --- a/testing/src/support/fixtures.ts +++ b/testing/src/support/fixtures.ts @@ -9,7 +9,6 @@ import { BrandingPage } from '../pages/_app/admin/branding/index.page'; import { BrandingLoginPagePage } from '../pages/_app/admin/branding/login-page.page'; import { InstrumentReposPage } from '../pages/_app/admin/instrument-repos/index.page'; import { AdminInstrumentsPage } from '../pages/_app/admin/instruments.page'; -import { MailSettingsPage } from '../pages/_app/admin/mail.page'; import { PermissionSetPage } from '../pages/_app/admin/permission-sets/$permissionSetId.page'; import { CreatePermissionSetPage } from '../pages/_app/admin/permission-sets/create.page'; import { PermissionSetsPage } from '../pages/_app/admin/permission-sets/index.page'; @@ -43,7 +42,6 @@ const pageModels = { '/admin/branding/login-page': BrandingLoginPagePage, '/admin/instrument-repos': InstrumentReposPage, '/admin/instruments': AdminInstrumentsPage, - '/admin/mail': MailSettingsPage, '/admin/permission-sets': PermissionSetsPage, '/admin/permission-sets/$permissionSetId': PermissionSetPage, '/admin/permission-sets/create': CreatePermissionSetPage, From b231a53d606abc630f59f00c3962628c3b45927e Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:49:57 -0500 Subject: [PATCH 12/19] fix(web): hide the remote assignments settings on an instance without the gateway Without the gateway the server reports remote assignments as disabled whatever is saved, so the Enable Remote Assignments switch did nothing there. The whole Remote Assignments section is now hidden on such an instance, as the default validity already was. Co-Authored-By: Claude Opus 5.5 --- .../ApplicationSettings/FeaturesTab.tsx | 67 ++++++++++--------- .../__tests__/FeaturesTab.test.tsx | 3 +- 2 files changed, 38 insertions(+), 32 deletions(-) diff --git a/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx b/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx index 488c42d02..bef589c40 100644 --- a/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx +++ b/apps/web/src/components/ApplicationSettings/FeaturesTab.tsx @@ -42,45 +42,50 @@ export const FeaturesTab = ({ autosave }: FeaturesTabProps) => { label: t({ en: 'Uploader', es: 'Carga de datos', fr: 'Téléversement' }) }; + // An instance without the gateway can never create a remote assignment, and the server reports + // them disabled there whatever was saved, so neither setting could take effect. + if (!config.setup.isGatewayEnabled) { + return ; + } + const remoteAssignmentsLabel = t({ en: 'Enable Remote Assignments', es: 'Activar las tareas remotas', fr: 'Activer les tâches à distance' }); - const remoteAssignmentsRow = { - control: ( - autosave({ isBulkRemoteAssignmentsEnabled: checked })} - /> - ), - help: t({ - en: 'When enabled, the group links are collected under a Group Actions menu with an added page for assigning one or more instruments to many subjects at once. When disabled, those links stay where they are.', - es: 'Cuando está activada, los enlaces del grupo se reúnen bajo un menú Acciones del grupo con una página adicional para asignar uno o varios instrumentos a muchos sujetos a la vez. Cuando está desactivada, esos enlaces permanecen donde están.', - fr: 'Lorsqu’elle est activée, les liens de groupe sont regroupés sous un menu Actions de groupe avec une page permettant d’attribuer un ou plusieurs instruments à plusieurs sujets à la fois. Lorsqu’elle est désactivée, ces liens restent inchangés.' - }), - label: remoteAssignmentsLabel - }; - const durationRow = { - control: , - help: t({ - en: 'The number of days a new remote assignment stays valid by default. This only sets the initial expiry date when creating an assignment, which can still be changed for each one.', - es: 'El número de días que una nueva tarea remota permanece válida de forma predeterminada. Esto solo define la fecha de vencimiento inicial al crear una tarea, que se puede cambiar en cada caso.', - fr: "Le nombre de jours pendant lesquels une nouvelle tâche à distance reste valide par défaut. Ceci ne définit que la date d'expiration initiale lors de la création d'une tâche, qui peut toujours être modifiée pour chacune." - }), - label: t({ - en: 'Default Assignment Validity (Days)', - es: 'Validez predeterminada de las tareas (días)', - fr: 'Validité par défaut des tâches (jours)' - }) - }; const remoteAssignmentsSection = { content: ( , + help: t({ + en: 'The number of days a new remote assignment stays valid by default. This only sets the initial expiry date when creating an assignment, which can still be changed for each one.', + es: 'El número de días que una nueva tarea remota permanece válida de forma predeterminada. Esto solo define la fecha de vencimiento inicial al crear una tarea, que se puede cambiar en cada caso.', + fr: "Le nombre de jours pendant lesquels une nouvelle tâche à distance reste valide par défaut. Ceci ne définit que la date d'expiration initiale lors de la création d'une tâche, qui peut toujours être modifiée pour chacune." + }), + label: t({ + en: 'Default Assignment Validity (Days)', + es: 'Validez predeterminada de las tareas (días)', + fr: 'Validité par défaut des tâches (jours)' + }) + }, + { + control: ( + autosave({ isBulkRemoteAssignmentsEnabled: checked })} + /> + ), + help: t({ + en: 'When enabled, the group links are collected under a Group Actions menu with an added page for assigning one or more instruments to many subjects at once. When disabled, those links stay where they are.', + es: 'Cuando está activada, los enlaces del grupo se reúnen bajo un menú Acciones del grupo con una página adicional para asignar uno o varios instrumentos a muchos sujetos a la vez. Cuando está desactivada, esos enlaces permanecen donde están.', + fr: 'Lorsqu’elle est activée, les liens de groupe sont regroupés sous un menu Actions de groupe avec une page permettant d’attribuer un ou plusieurs instruments à plusieurs sujets à la fois. Lorsqu’elle est désactivée, ces liens restent inchangés.' + }), + label: remoteAssignmentsLabel + } + ]} /> ), label: t({ en: 'Remote Assignments', es: 'Tareas remotas', fr: 'Tâches à distance' }) diff --git a/apps/web/src/components/ApplicationSettings/__tests__/FeaturesTab.test.tsx b/apps/web/src/components/ApplicationSettings/__tests__/FeaturesTab.test.tsx index c5881579c..69baa404d 100644 --- a/apps/web/src/components/ApplicationSettings/__tests__/FeaturesTab.test.tsx +++ b/apps/web/src/components/ApplicationSettings/__tests__/FeaturesTab.test.tsx @@ -78,9 +78,10 @@ describe('FeaturesTab', () => { expect(screen.getByTestId('default-assignment-duration-input')).toBeTruthy(); }); - it('should not offer the validity on an instance without the gateway, which cannot create remote assignments', () => { + it('should hide remote assignments on an instance without the gateway, where neither setting could take effect', () => { mocks.config.setup.isGatewayEnabled = false; renderTab(); + expect(sectionLabels()).toStrictEqual(['Uploader']); expect(screen.queryByTestId('default-assignment-duration-input')).toBeNull(); }); From bcb6ae641dd175ce11c1d03169f3cbae47168a91 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:42:42 -0500 Subject: [PATCH 13/19] feat(subject-utils): derive a subject id from custom identifying fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Groundwork for the CUSTOM_FIELDS identification method (#1546), which derives a subject's id in the browser from fields an admin defines. - normalizeCustomFieldValue uppercases, applies NFKD, spells out the Latin letters NFKD leaves whole (Œ, Æ, Ø, Ł, Đ, Ð, Þ) and keeps only letters and digits. It does not use transliteration, which spells 李 and 里 alike. - deriveCustomFieldsSubjectId normalizes each value itself, refuses an empty list or a value that normalizes to nothing, and returns cf_ plus the lowercase hex of PBKDF2-SHA-256 over the UTF-8 JSON array of the normalized values, with the given iteration count and a 32-byte salt passed as 64 lowercase hex characters. It uses crypto.subtle, so it runs in the browser. - isCustomFieldsSubjectId checks the cf_ shape, and toStoredSubjectId never scopes a cf_ id to a group. Every expected id in the tests was computed separately with Node's pbkdf2Sync, one of them at 600,000 iterations. The normalization steps, the letter table, the encoding and the cf_ prefix cannot change once an instance has used them: the typed values are never stored. Co-Authored-By: Claude Opus 5.5 --- .../subject-utils/src/__tests__/index.test.ts | 117 ++++++++++++++++++ packages/subject-utils/src/index.ts | 79 +++++++++++- 2 files changed, 194 insertions(+), 2 deletions(-) diff --git a/packages/subject-utils/src/__tests__/index.test.ts b/packages/subject-utils/src/__tests__/index.test.ts index c80cf7172..1dc3042ae 100644 --- a/packages/subject-utils/src/__tests__/index.test.ts +++ b/packages/subject-utils/src/__tests__/index.test.ts @@ -2,10 +2,13 @@ import type { ClinicalSubjectIdentificationData } from '@opendatacapture/schemas import { describe, expect, it } from 'vitest'; import { + deriveCustomFieldsSubjectId, encodeScopedSubjectId, generateSubjectHash, inferSubjectIdentificationMethod, + isCustomFieldsSubjectId, isSubjectWithPersonalInfo, + normalizeCustomFieldValue, removeSubjectIdScope, toStoredSubjectId } from '../index.js'; @@ -19,6 +22,8 @@ const validIdentificationData = { const nameHash = '520be817915752b50f418a743a54b692ce8e2a0a3421931598ffad246182568f'; +const customFieldsSubjectId = 'cf_1284ad542e92c54dbe37f0dc1f37114bb4ca53d7000a810e7c30359f15d7ec34'; + describe('generateSubjectHash', () => { it('should hash valid clinical identification data to a deterministic string', async () => { await expect(generateSubjectHash(validIdentificationData)).resolves.toEqual( @@ -206,4 +211,116 @@ describe('toStoredSubjectId', () => { it('should leave a value that already holds a scope alone', () => { expect(toStoredSubjectId('Other_Group$ex_111', { groupName: 'My Group' })).toBe('Other_Group$ex_111'); }); + it('should leave a custom-fields id unscoped, so it names the subject every group shares', () => { + expect(toStoredSubjectId(customFieldsSubjectId, { groupName: 'My Group' })).toBe(customFieldsSubjectId); + }); +}); + +describe('isCustomFieldsSubjectId', () => { + it('should accept cf_ followed by 64 lowercase hex characters', () => { + expect(isCustomFieldsSubjectId(customFieldsSubjectId)).toBe(true); + }); + it('should reject uppercase hex, which derivation never writes', () => { + expect(isCustomFieldsSubjectId(`cf_${nameHash.toUpperCase()}`)).toBe(false); + }); + it('should reject a digest of the wrong length', () => { + expect(isCustomFieldsSubjectId(customFieldsSubjectId.slice(0, -1))).toBe(false); + }); + it('should reject a bare digest, which is a name hash', () => { + expect(isCustomFieldsSubjectId(nameHash)).toBe(false); + }); +}); + +describe('normalizeCustomFieldValue', () => { + it.each([ + ['Jané', 'JANE'], + ['Jean Paul', 'JEANPAUL'], + ['Jean\u2011Paul', 'JEANPAUL'], + ["O'Brien", 'OBRIEN'], + ['ab-12 34', 'AB1234'], + ['1234', '1234'], + ['Straße', 'STRASSE'], + ['Иван', 'ИВАН'] + ])('should keep only the uppercase letters and digits of %s, giving %s', (typed, normalized) => { + expect(normalizeCustomFieldValue(typed)).toBe(normalized); + }); + it.each([ + ['Lebœuf', 'LEBOEUF'], + ['Ægir', 'AEGIR'], + ['Sørensen', 'SORENSEN'], + ['Łukasz', 'LUKASZ'], + ['Đorđe', 'DORDE'], + ['Ðóra', 'DORA'], + ['Þór', 'THOR'] + ])('should spell out the letters NFKD leaves whole, so %s becomes %s', (typed, normalized) => { + expect(normalizeCustomFieldValue(typed)).toBe(normalized); + }); + it('should keep 李 and 里 apart, so two subjects are never merged', () => { + expect([normalizeCustomFieldValue('李'), normalizeCustomFieldValue('里')]).toEqual(['李', '里']); + }); + it('should remove a combining mark that uppercasing introduces, so ǰ becomes J', () => { + expect(normalizeCustomFieldValue('ǰ')).toBe('J'); + }); + it('should normalize punctuation alone to an empty string', () => { + expect(normalizeCustomFieldValue(' -/. ')).toBe(''); + }); +}); + +describe('deriveCustomFieldsSubjectId', () => { + const salt = '000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'; + + it('should derive with PBKDF2-SHA-256 over the JSON array of normalized values at 600,000 iterations', async () => { + await expect(deriveCustomFieldsSubjectId(['AB12', 'REX'], { iterations: 600_000, salt })).resolves.toBe( + 'cf_1284ad542e92c54dbe37f0dc1f37114bb4ca53d7000a810e7c30359f15d7ec34' + ); + }); + it('should use the iteration count it is given', async () => { + await expect(deriveCustomFieldsSubjectId(['AB12', 'REX'], { iterations: 1000, salt })).resolves.toBe( + 'cf_55bf9f2b20c484237eb7ff3a865164f9436c155b4ed7051db5282c45224959af' + ); + }); + it('should normalize each value itself, so a caller cannot forget to', async () => { + await expect(deriveCustomFieldsSubjectId(['ab-12', ' Rex '], { iterations: 1000, salt })).resolves.toBe( + 'cf_55bf9f2b20c484237eb7ff3a865164f9436c155b4ed7051db5282c45224959af' + ); + }); + it('should keep field boundaries, so ["AB", "C"] and ["A", "BC"] are different subjects', async () => { + await expect( + Promise.all([ + deriveCustomFieldsSubjectId(['AB', 'C'], { iterations: 1000, salt }), + deriveCustomFieldsSubjectId(['A', 'BC'], { iterations: 1000, salt }) + ]) + ).resolves.toEqual([ + 'cf_b259140eea61c11ee9ae9e9c588c8658cd07b34becd5384d522434beb51df58b', + 'cf_7c273fcc2043db276f976eca3f6d342152d8f86ad75e58e8d6d6a801f02c4504' + ]); + }); + it('should hash the UTF-8 encoding, so 李 and 里 give different ids', async () => { + await expect( + Promise.all([ + deriveCustomFieldsSubjectId(['李'], { iterations: 1000, salt }), + deriveCustomFieldsSubjectId(['里'], { iterations: 1000, salt }) + ]) + ).resolves.toEqual([ + 'cf_b8371d43ffc6f1407359605879b8705cda6689915f39b7499fc92a0d5f3c4b22', + 'cf_ee997483bb6ef14ebb034cb15635cf14b8f5a7a5a0487ea6ccd971fc3d281f8f' + ]); + }); + it('should derive an id isCustomFieldsSubjectId accepts', async () => { + const id = await deriveCustomFieldsSubjectId(['AB12'], { iterations: 1, salt }); + expect(isCustomFieldsSubjectId(id)).toBe(true); + }); + it('should refuse a value that normalizes to nothing, rather than hash an empty field', async () => { + await expect(deriveCustomFieldsSubjectId(['AB12', '--'], { iterations: 1000, salt })).rejects.toThrow( + /letter or digit/ + ); + }); + it('should refuse an empty list of values, which would give every subject the same id', async () => { + await expect(deriveCustomFieldsSubjectId([], { iterations: 1000, salt })).rejects.toThrow(/at least one value/); + }); + it('should refuse a salt that is not 64 lowercase hex characters, rather than derive from misread bytes', async () => { + await expect(deriveCustomFieldsSubjectId(['AB12'], { iterations: 1000, salt: salt.toUpperCase() })).rejects.toThrow( + /salt/ + ); + }); }); diff --git a/packages/subject-utils/src/index.ts b/packages/subject-utils/src/index.ts index 920065103..9ec5985ed 100644 --- a/packages/subject-utils/src/index.ts +++ b/packages/subject-utils/src/index.ts @@ -12,6 +12,35 @@ type SubjectPersonalInfo = Pick { + return Number.parseInt(salt.slice(index * 2, index * 2 + 2), 16); + }); +} + +function encodeLowercaseHex(bytes: ArrayBuffer) { + return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, '0')).join(''); +} + function parseClinicalSubjectIdentificationData({ dateOfBirth, firstName, @@ -66,12 +95,58 @@ export function inferSubjectIdentificationMethod(subjectId: string): SubjectIden return PERSONAL_INFO_SUBJECT_ID_PATTERN.test(subjectId) ? 'PERSONAL_INFO' : 'CUSTOM_ID'; } +export function isCustomFieldsSubjectId(subjectId: string): boolean { + return CUSTOM_FIELDS_SUBJECT_ID_PATTERN.test(subjectId); +} + export function toStoredSubjectId(enteredId: string, options: { groupName: string }): string { - // Only a custom id belongs to a group; a name hash names the same subject in every group. - if (enteredId.includes('$') || inferSubjectIdentificationMethod(enteredId) !== 'CUSTOM_ID') { + // Only a custom id belongs to a group; a name hash or a custom-fields id names the same subject in every group. + if ( + enteredId.includes('$') || + isCustomFieldsSubjectId(enteredId) || + inferSubjectIdentificationMethod(enteredId) !== 'CUSTOM_ID' + ) { return enteredId; } return encodeScopedSubjectId(enteredId, options); } +// Every step, in this order, and the letter table are part of each stored cf_ id: the typed values +// are never stored, so no id can be recomputed after a change. Uppercasing goes first because it +// can add a combining mark (ǰ becomes J and a caron) that the last step removes. transliteration is +// not used because it spells 李 and 里 alike, which would merge two subjects. +export function normalizeCustomFieldValue(value: string): string { + let normalized = value.toUpperCase().normalize('NFKD'); + for (const [letter, spelling] of UNDECOMPOSABLE_LETTER_SPELLINGS) { + normalized = normalized.replaceAll(letter, spelling); + } + return normalized.replaceAll(/[^\p{L}\p{N}]/gu, ''); +} + +export async function deriveCustomFieldsSubjectId( + typedValues: readonly string[], + options: { iterations: number; salt: string } +): Promise { + if (typedValues.length === 0) { + throw new Error('Invalid custom field values: Expected at least one value.'); + } + const normalizedValues = typedValues.map((value) => normalizeCustomFieldValue(value)); + if (normalizedValues.includes('')) { + throw new Error('Invalid custom field value: Expected at least one letter or digit.'); + } + const key = await crypto.subtle.importKey( + 'raw', + new TextEncoder().encode(JSON.stringify(normalizedValues)), + 'PBKDF2', + false, + ['deriveBits'] + ); + const derivedBits = await crypto.subtle.deriveBits( + { hash: 'SHA-256', iterations: options.iterations, name: 'PBKDF2', salt: decodeCustomFieldsSalt(options.salt) }, + key, + 256 + ); + return CUSTOM_FIELDS_SUBJECT_ID_PREFIX + encodeLowercaseHex(derivedBits); +} + export { removeSubjectIdScope } from '@opendatacapture/runtime-internal'; From ad1a542383a78f18c10f97cf7d5688b0763ab9d6 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 10:43:00 -0500 Subject: [PATCH 14/19] docs(subject-utils): list the scoping and custom-fields exports The package guide named four exports. It now names the five added for the shared scoping rule and the custom-fields method as well. Co-Authored-By: Claude Opus 5.5 --- packages/subject-utils/AGENTS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/subject-utils/AGENTS.md b/packages/subject-utils/AGENTS.md index 331246fb2..532b77c5d 100644 --- a/packages/subject-utils/AGENTS.md +++ b/packages/subject-utils/AGENTS.md @@ -1,7 +1,9 @@ # packages/subject-utils -Derives and formats clinical subject identifiers. Four exports: `generateSubjectHash`, -`encodeScopedSubjectId`, `isSubjectWithPersonalInfo`, and `removeSubjectIdScope` (re-exported from +Derives and formats clinical subject identifiers. Nine exports: `generateSubjectHash`, +`encodeScopedSubjectId`, `isSubjectWithPersonalInfo`, `inferSubjectIdentificationMethod`, +`toStoredSubjectId`, `isCustomFieldsSubjectId`, `normalizeCustomFieldValue`, +`deriveCustomFieldsSubjectId`, and `removeSubjectIdScope` (re-exported from `@opendatacapture/runtime-internal`). Source-only — `exports` is `"./src/index.ts"`, no build step. Used by `apps/web`, `apps/api` and `packages/react-core`. From 10d64a376037b17e8cf9db18a40b33ce4b8d33f9 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 11:20:39 -0500 Subject: [PATCH 15/19] feat(api): store an administrator's definition of fields that identify subjects GET and PUT /v1/subjects/identification/settings read and write a definition of custom identifying fields: a label for the method and an ordered list of one to ten fields, each with a label, optional help text, a pattern and an optional error message. Patterns are checked by compiling them as the browser will test them: as a whole-value match with the u flag. The server gives a first definition a random 32-byte salt and 600,000 PBKDF2 iterations and keeps both. Once any subject id carries the cf_ prefix, the definition is locked: it cannot be removed and its number of fields cannot change, though labels, help text, messages and patterns can. The salt is served to every user who can read subjects, since the browser derives the id, and never on the public setup route. Subjects with a cf_ id are kept out of the custom-id suggestions. Refs #1546 Co-Authored-By: Claude Opus 5.5 --- apps/api/prisma/schema.prisma | 23 +++ .../subject-identification.service.test.ts | 169 ++++++++++++++++++ .../__tests__/subjects.controller.test.ts | 21 ++- .../__tests__/subjects.service.test.ts | 10 ++ .../subject-identification.service.ts | 82 +++++++++ apps/api/src/subjects/subjects.controller.ts | 33 +++- apps/api/src/subjects/subjects.module.ts | 3 +- apps/api/src/subjects/subjects.service.ts | 18 +- .../suites/11-subject-identification.suite.ts | 155 ++++++++++++++++ packages/schemas/package.json | 1 + .../__tests__/subject-identification.test.ts | 78 ++++++++ .../subject-identification.ts | 85 +++++++++ packages/subject-utils/src/index.ts | 4 +- 13 files changed, 674 insertions(+), 8 deletions(-) create mode 100644 apps/api/src/subjects/__tests__/subject-identification.service.test.ts create mode 100644 apps/api/src/subjects/subject-identification.service.ts create mode 100644 apps/api/test/suites/11-subject-identification.suite.ts create mode 100644 packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts create mode 100644 packages/schemas/src/subject-identification/subject-identification.ts diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index f8c0e7acd..754fa03b8 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -522,6 +522,28 @@ type MailTemplate { subject LocalizedString? } +// One field an administrator defines for identifying subjects. Fields are hashed in the order they +// are stored, so a field's position is its identity. +type CustomIdentificationField { + description LocalizedString? + label LocalizedString + pattern String + patternErrorMessage LocalizedString? +} + +// The salt and the iteration count are generated with the first definition and never change: every +// id derived from the fields depends on them, and the values typed into the fields are not stored. +type CustomFieldsDefinition { + fields CustomIdentificationField[] + iterations Int + label LocalizedString + salt String +} + +type SubjectIdentificationSettings { + customFields CustomFieldsDefinition? +} + model SetupState { createdAt DateTime @default(now()) @db.Date updatedAt DateTime @updatedAt @db.Date @@ -535,6 +557,7 @@ model SetupState { isSetup Boolean mailConfig MailConfig? newUserEmailTemplate MailTemplate? + subjectIdentificationSettings SubjectIdentificationSettings? tableColorMode TableColorMode? @@map("SetupStateModel") diff --git a/apps/api/src/subjects/__tests__/subject-identification.service.test.ts b/apps/api/src/subjects/__tests__/subject-identification.service.test.ts new file mode 100644 index 000000000..f49e18cf0 --- /dev/null +++ b/apps/api/src/subjects/__tests__/subject-identification.service.test.ts @@ -0,0 +1,169 @@ +import type { Model } from '@douglasneuroinformatics/libnest'; +import { getModelToken } from '@douglasneuroinformatics/libnest'; +import { MockFactory } from '@douglasneuroinformatics/libnest/testing'; +import type { MockedInstance } from '@douglasneuroinformatics/libnest/testing'; +import { ConflictException, InternalServerErrorException, ServiceUnavailableException } from '@nestjs/common'; +import { Test } from '@nestjs/testing'; +import type { CustomFieldsDefinitionData } from '@opendatacapture/schemas/subject-identification'; +import { beforeEach, describe, expect, it } from 'vitest'; + +import { SubjectIdentificationService } from '../subject-identification.service'; +import { SubjectsService } from '../subjects.service'; + +const field = (label: string) => ({ label: { en: label }, pattern: '[0-9]+' }); + +const definitionData: CustomFieldsDefinitionData = { + fields: [field('Animal ID'), field('Cage')], + label: { en: 'Animal information' } +}; + +const storedDefinition = { ...definitionData, iterations: 1000, salt: 'ab'.repeat(32) }; + +const setupState = (customFields: null | typeof storedDefinition = null) => ({ + id: 'setup-1', + isSetup: true, + subjectIdentificationSettings: customFields ? { customFields } : null +}); + +describe('SubjectIdentificationService', () => { + let service: SubjectIdentificationService; + let setupStateModel: MockedInstance>; + let subjectsService: MockedInstance; + + const savedCustomFields = () => { + return setupStateModel.update.mock.lastCall?.[0].data.subjectIdentificationSettings.set.customFields; + }; + + beforeEach(async () => { + const moduleRef = await Test.createTestingModule({ + providers: [ + SubjectIdentificationService, + MockFactory.createForModelToken(getModelToken('SetupState')), + MockFactory.createForService(SubjectsService) + ] + }).compile(); + service = moduleRef.get(SubjectIdentificationService); + setupStateModel = moduleRef.get(getModelToken('SetupState')); + subjectsService = moduleRef.get(SubjectsService); + subjectsService.hasCustomFieldsSubjects.mockResolvedValue(false); + }); + + describe('getSettings', () => { + it('should read an instance that never saved settings as having no definition', async () => { + setupStateModel.findFirst.mockResolvedValueOnce({ subjectIdentificationSettings: null }); + await expect(service.getSettings()).resolves.toStrictEqual({ customFields: null, isCustomFieldsLocked: false }); + }); + + it('should read an instance with no setup state as having no definition', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(null); + await expect(service.getSettings()).resolves.toMatchObject({ customFields: null }); + }); + + it('should return the stored definition, salt included, since the browser derives ids from it', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await expect(service.getSettings()).resolves.toMatchObject({ customFields: storedDefinition }); + }); + + it('should report the definition locked once any subject has an id derived from it', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + subjectsService.hasCustomFieldsSubjects.mockResolvedValueOnce(true); + await expect(service.getSettings()).resolves.toMatchObject({ isCustomFieldsLocked: true }); + }); + }); + + describe('updateSettings', () => { + it('should refuse to save before the instance is set up', async () => { + setupStateModel.findFirst.mockResolvedValueOnce({ isSetup: false }); + await expect(service.updateSettings({ customFields: definitionData })).rejects.toBeInstanceOf( + ServiceUnavailableException + ); + }); + + it('should give a first definition a random 32-byte salt and 600,000 iterations', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState()); + await service.updateSettings({ customFields: definitionData }); + expect(savedCustomFields()).toStrictEqual({ + ...definitionData, + iterations: 600_000, + salt: expect.stringMatching(/^[0-9a-f]{64}$/) + }); + }); + + it('should give two instances different salts, so their ids are not comparable', async () => { + setupStateModel.findFirst.mockResolvedValue(setupState()); + await service.updateSettings({ customFields: definitionData }); + const first = savedCustomFields().salt; + await service.updateSettings({ customFields: definitionData }); + expect(savedCustomFields().salt).not.toBe(first); + }); + + it('should keep the stored salt and iteration count when the definition is saved again', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await service.updateSettings({ customFields: { ...definitionData, label: { en: 'Mouse information' } } }); + expect(savedCustomFields()).toMatchObject({ + iterations: 1000, + label: { en: 'Mouse information' }, + salt: 'ab'.repeat(32) + }); + }); + + it('should remove the definition while no subject has been identified with it', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await service.updateSettings({ customFields: null }); + expect(savedCustomFields()).toBeNull(); + }); + + it('should let the fields be added to or removed while no subject has been identified with them', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await service.updateSettings({ customFields: { ...definitionData, fields: [field('Animal ID')] } }); + expect(savedCustomFields().fields).toHaveLength(1); + }); + + describe('once a subject has been identified with the fields', () => { + beforeEach(() => { + subjectsService.hasCustomFieldsSubjects.mockResolvedValue(true); + }); + + it('should refuse to remove the definition', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await expect(service.updateSettings({ customFields: null })).rejects.toBeInstanceOf(ConflictException); + expect(setupStateModel.update).not.toHaveBeenCalled(); + }); + + it('should refuse to change the number of fields', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await expect( + service.updateSettings({ customFields: { ...definitionData, fields: [field('Animal ID')] } }) + ).rejects.toBeInstanceOf(ConflictException); + expect(setupStateModel.update).not.toHaveBeenCalled(); + }); + + it('should still let labels, help text, messages and patterns be corrected, since none of them is hashed', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + const corrected = { + fields: [ + { ...field('Animal identifier'), description: { en: 'On the ear tag' }, pattern: '[0-9]{4}' }, + { ...field('Cage number'), patternErrorMessage: { en: 'Digits only' } } + ], + label: { en: 'Mouse' } + }; + await service.updateSettings({ customFields: corrected }); + expect(savedCustomFields()).toStrictEqual({ ...corrected, iterations: 1000, salt: 'ab'.repeat(32) }); + }); + + it('should fail loudly when subjects were identified with fields that are no longer stored', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState()); + await expect(service.updateSettings({ customFields: definitionData })).rejects.toBeInstanceOf( + InternalServerErrorException + ); + }); + }); + + it('should return the settings as they now stand', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState()).mockResolvedValueOnce(setupState(storedDefinition)); + await expect(service.updateSettings({ customFields: definitionData })).resolves.toMatchObject({ + customFields: storedDefinition + }); + }); + }); +}); diff --git a/apps/api/src/subjects/__tests__/subjects.controller.test.ts b/apps/api/src/subjects/__tests__/subjects.controller.test.ts index 4da5ec400..0bcc9b0f8 100644 --- a/apps/api/src/subjects/__tests__/subjects.controller.test.ts +++ b/apps/api/src/subjects/__tests__/subjects.controller.test.ts @@ -7,6 +7,7 @@ import { beforeEach, describe, expect, it } from 'vitest'; import { createAppAbility } from '@/auth/ability.utils'; +import { SubjectIdentificationService } from '../subject-identification.service'; import { SubjectsController } from '../subjects.controller'; import { SubjectsService } from '../subjects.service'; @@ -22,17 +23,35 @@ function getDeleteIdPipe(): ParseSchemaPipe { describe('SubjectsController', () => { let subjectsController: SubjectsController; + let subjectIdentificationService: MockedInstance; let subjectsService: MockedInstance; beforeEach(async () => { const moduleRef = await Test.createTestingModule({ controllers: [SubjectsController], - providers: [MockFactory.createForService(SubjectsService)] + providers: [ + MockFactory.createForService(SubjectIdentificationService), + MockFactory.createForService(SubjectsService) + ] }).compile(); subjectsController = moduleRef.get(SubjectsController); + subjectIdentificationService = moduleRef.get(SubjectIdentificationService); subjectsService = moduleRef.get(SubjectsService); }); + it('should return the subject identification settings', async () => { + const settings = { customFields: null, isCustomFieldsLocked: false }; + subjectIdentificationService.getSettings.mockResolvedValueOnce(settings); + await expect(subjectsController.getIdentificationSettings()).resolves.toBe(settings); + }); + + it('should update the subject identification settings', async () => { + const settings = { customFields: null, isCustomFieldsLocked: false }; + subjectIdentificationService.updateSettings.mockResolvedValueOnce(settings); + await expect(subjectsController.updateIdentificationSettings({ customFields: null })).resolves.toBe(settings); + expect(subjectIdentificationService.updateSettings).toHaveBeenCalledWith({ customFields: null }); + }); + it('should delete a subject within what the caller may delete, forcing when asked', async () => { subjectsService.deleteById.mockResolvedValue({ id: 'subject-1' }); diff --git a/apps/api/src/subjects/__tests__/subjects.service.test.ts b/apps/api/src/subjects/__tests__/subjects.service.test.ts index c0a9a5a1c..10631b73e 100644 --- a/apps/api/src/subjects/__tests__/subjects.service.test.ts +++ b/apps/api/src/subjects/__tests__/subjects.service.test.ts @@ -454,6 +454,7 @@ describe('SubjectsService', () => { subjectModel.findMany.mockResolvedValueOnce([]); await subjectsService.findCustomIds('group-1'); expect(findManyArgs().where.AND).toContainEqual({ + NOT: { id: { gte: 'cf_', lt: 'cf`' } }, OR: [ { dateOfBirth: null }, { dateOfBirth: { isSet: false } }, @@ -468,6 +469,15 @@ describe('SubjectsService', () => { }); }); + describe('hasCustomFieldsSubjects', () => { + // A custom-fields subject stores no name, so only its id tells it apart from a custom id. + it('should look for any subject whose id carries the custom-fields prefix, by a lexical range', async () => { + subjectModel.exists.mockResolvedValueOnce(true); + await expect(subjectsService.hasCustomFieldsSubjects()).resolves.toBe(true); + expect(subjectModel.exists).toHaveBeenCalledWith({ id: { gte: 'cf_', lt: 'cf`' } }); + }); + }); + describe('findDefaultGroupCustomIds', () => { const findManyArgs = () => { return subjectModel.findMany.mock.lastCall?.[0] as { select: unknown; where: { AND: unknown[] } }; diff --git a/apps/api/src/subjects/subject-identification.service.ts b/apps/api/src/subjects/subject-identification.service.ts new file mode 100644 index 000000000..29aff76a6 --- /dev/null +++ b/apps/api/src/subjects/subject-identification.service.ts @@ -0,0 +1,82 @@ +import { randomBytes } from 'node:crypto'; + +import { InjectModel } from '@douglasneuroinformatics/libnest'; +import type { Model } from '@douglasneuroinformatics/libnest'; +import { + ConflictException, + Injectable, + InternalServerErrorException, + ServiceUnavailableException +} from '@nestjs/common'; +import type { + $UpdateSubjectIdentificationSettingsData, + SubjectIdentificationSettings +} from '@opendatacapture/schemas/subject-identification'; + +import { SubjectsService } from './subjects.service'; + +/** + * The PBKDF2 iteration count given to a new definition. It is stored with the definition, so raising + * it here changes only the instances that define their fields afterwards. + */ +const CUSTOM_FIELDS_ITERATIONS = 600_000; + +const CUSTOM_FIELDS_SALT_BYTES = 32; + +@Injectable() +export class SubjectIdentificationService { + constructor( + @InjectModel('SetupState') private readonly setupStateModel: Model<'SetupState'>, + private readonly subjectsService: SubjectsService + ) {} + + async getSettings(): Promise { + const setupState = await this.setupStateModel.findFirst({ select: { subjectIdentificationSettings: true } }); + return { + customFields: setupState?.subjectIdentificationSettings?.customFields ?? null, + isCustomFieldsLocked: await this.subjectsService.hasCustomFieldsSubjects() + }; + } + + async updateSettings({ + customFields + }: $UpdateSubjectIdentificationSettingsData): Promise { + const setupState = await this.setupStateModel.findFirst(); + if (!setupState?.isSetup) { + throw new ServiceUnavailableException('Cannot update subject identification settings before setup'); + } + const stored = setupState.subjectIdentificationSettings?.customFields ?? null; + // The values typed into the fields are never stored, so once an id has been derived from them, a + // different salt, iteration count or list of fields could never produce that id again. + if (await this.subjectsService.hasCustomFieldsSubjects()) { + if (!stored) { + throw new InternalServerErrorException( + 'Subjects are identified by custom fields, but no definition of the fields is stored' + ); + } else if (!customFields) { + throw new ConflictException( + 'The custom identifying fields cannot be removed once a subject has been identified with them' + ); + } else if (customFields.fields.length !== stored.fields.length) { + throw new ConflictException( + 'The number of custom identifying fields cannot change once a subject has been identified with them' + ); + } + } + await this.setupStateModel.update({ + data: { + subjectIdentificationSettings: { + set: { + customFields: customFields && { + ...customFields, + iterations: stored?.iterations ?? CUSTOM_FIELDS_ITERATIONS, + salt: stored?.salt ?? randomBytes(CUSTOM_FIELDS_SALT_BYTES).toString('hex') + } + } + } + }, + where: { id: setupState.id } + }); + return this.getSettings(); + } +} diff --git a/apps/api/src/subjects/subjects.controller.ts b/apps/api/src/subjects/subjects.controller.ts index ce6227b68..95dff7a65 100644 --- a/apps/api/src/subjects/subjects.controller.ts +++ b/apps/api/src/subjects/subjects.controller.ts @@ -1,16 +1,22 @@ import { $BooleanLike } from '@douglasneuroinformatics/libjs'; import { ApiOperation, CurrentUser, ParseSchemaPipe, ValidObjectIdPipe } from '@douglasneuroinformatics/libnest'; -import { Controller, Delete, Get, Param, Query } from '@nestjs/common'; +import { Body, Controller, Delete, Get, Param, Put, Query } from '@nestjs/common'; +import { $UpdateSubjectIdentificationSettingsData } from '@opendatacapture/schemas/subject-identification'; +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; import z from 'zod/v4'; import type { AppAbility } from '@/auth/auth.types'; -import { RouteAccess } from '@/core/decorators/route-access.decorator'; +import { ADMIN_ONLY, RouteAccess } from '@/core/decorators/route-access.decorator'; +import { SubjectIdentificationService } from './subject-identification.service'; import { SubjectsService } from './subjects.service'; @Controller('subjects') export class SubjectsController { - constructor(private readonly subjectsService: SubjectsService) {} + constructor( + private readonly subjectIdentificationService: SubjectIdentificationService, + private readonly subjectsService: SubjectsService + ) {} @ApiOperation({ summary: 'Delete Subject' }) @Delete(':id') @@ -55,4 +61,25 @@ export class SubjectsController { findDefaultGroupCustomIds(@CurrentUser('ability') ability: AppAbility) { return this.subjectsService.findDefaultGroupCustomIds({ ability }); } + + // Two segments, so `@Get(':id')` cannot capture the path whatever order the handlers are in. + @ApiOperation({ + description: + 'Every user who can read subjects can read the settings, salt included: the browser derives a custom-fields id itself, so the values typed never reach the server.', + summary: 'Get Subject Identification Settings' + }) + @Get('identification/settings') + @RouteAccess({ action: 'read', subject: 'Subject' }) + getIdentificationSettings(): Promise { + return this.subjectIdentificationService.getSettings(); + } + + @ApiOperation({ summary: 'Update Subject Identification Settings' }) + @Put('identification/settings') + @RouteAccess(ADMIN_ONLY) + updateIdentificationSettings( + @Body() data: $UpdateSubjectIdentificationSettingsData + ): Promise { + return this.subjectIdentificationService.updateSettings(data); + } } diff --git a/apps/api/src/subjects/subjects.module.ts b/apps/api/src/subjects/subjects.module.ts index 21894fe9b..c92065896 100644 --- a/apps/api/src/subjects/subjects.module.ts +++ b/apps/api/src/subjects/subjects.module.ts @@ -2,6 +2,7 @@ import { Module } from '@nestjs/common'; import { StorageModule } from '@/storage/storage.module'; +import { SubjectIdentificationService } from './subject-identification.service'; import { SubjectsController } from './subjects.controller'; import { SubjectsService } from './subjects.service'; @@ -9,6 +10,6 @@ import { SubjectsService } from './subjects.service'; controllers: [SubjectsController], exports: [SubjectsService], imports: [StorageModule], - providers: [SubjectsService] + providers: [SubjectIdentificationService, SubjectsService] }) export class SubjectsModule {} diff --git a/apps/api/src/subjects/subjects.service.ts b/apps/api/src/subjects/subjects.service.ts index 8a722accd..835b84bed 100644 --- a/apps/api/src/subjects/subjects.service.ts +++ b/apps/api/src/subjects/subjects.service.ts @@ -3,7 +3,7 @@ import type { Model } from '@douglasneuroinformatics/libnest'; import { ConflictException, Injectable, NotFoundException } from '@nestjs/common'; import { DEFAULT_GROUP_NAME } from '@opendatacapture/schemas/core'; import { $CreateSubjectData } from '@opendatacapture/schemas/subject'; -import { encodeScopedSubjectId } from '@opendatacapture/subject-utils'; +import { CUSTOM_FIELDS_SUBJECT_ID_PREFIX, encodeScopedSubjectId } from '@opendatacapture/subject-utils'; import type { Prisma } from '@prisma/client'; import { accessibleQuery } from '@/auth/ability.utils'; @@ -23,8 +23,14 @@ function idsWithPrefix(prefix: string): Prisma.StringFilter { return { gte: prefix, lt: prefix.slice(0, -1) + String.fromCharCode(lastCharCode + 1) }; } -/** A subject identified by personal information has every one of these fields set. */ +const IDENTIFIED_BY_CUSTOM_FIELDS: Prisma.SubjectWhereInput = { id: idsWithPrefix(CUSTOM_FIELDS_SUBJECT_ID_PREFIX) }; + +/** + * A subject identified by personal information has every one of these fields set. A subject + * identified by custom fields stores none of them either, so it is told apart by its id. + */ const IDENTIFIED_BY_CUSTOM_ID: Prisma.SubjectWhereInput = { + NOT: IDENTIFIED_BY_CUSTOM_FIELDS, OR: PERSONAL_INFO_FIELDS.flatMap((field) => [{ [field]: null }, { [field]: { isSet: false } }]) }; @@ -247,6 +253,14 @@ export class SubjectsService { return subjects.map((subject) => subject.id); } + /** + * Whether any subject in the instance, in any group, has an id derived from the custom fields. It + * is deliberately unscoped: the definition locks for everyone once anyone has used it. + */ + async hasCustomFieldsSubjects(): Promise { + return this.subjectModel.exists(IDENTIFIED_BY_CUSTOM_FIELDS); + } + /** * The ids of subjects having at least one record, for the "with records only" filter. * diff --git a/apps/api/test/suites/11-subject-identification.suite.ts b/apps/api/test/suites/11-subject-identification.suite.ts new file mode 100644 index 000000000..7596f19d2 --- /dev/null +++ b/apps/api/test/suites/11-subject-identification.suite.ts @@ -0,0 +1,155 @@ +import { randomUUID } from 'node:crypto'; + +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { beforeAll, describe, expect, it } from 'vitest'; + +import { defineSuite } from '../helpers'; + +type AuthHeaders = { authorization: string }; + +const PASSWORD = 'DataCapture2025_Test'; + +// Its own address, so these logins never count against another suite's throttling budget. +const LOGIN_ADDRESS = '192.0.2.111'; + +const definition = { + fields: [ + { label: { en: 'Animal ID' }, pattern: '[A-Z]{2}[0-9]+' }, + { label: { en: 'Cage' }, pattern: '[0-9]+' } + ], + label: { en: 'Animal information' } +}; + +export default defineSuite('subject identification', function () { + let adminHeaders: AuthHeaders; + let standardHeaders: AuthHeaders; + let groupId: string; + + const login = async (username: string): Promise => { + const response = await this.app.inject({ + method: 'POST', + payload: { password: PASSWORD, username }, + remoteAddress: LOGIN_ADDRESS, + url: '/v1/auth/login' + }); + expect(response.statusCode).toBe(200); + return { authorization: `Bearer ${response.json<{ accessToken: string }>().accessToken}` }; + }; + + const getSettings = async (headers: AuthHeaders) => { + const response = await this.app.inject({ headers, method: 'GET', url: '/v1/subjects/identification/settings' }); + expect(response.statusCode).toBe(200); + return response.json(); + }; + + const putSettings = (headers: AuthHeaders, payload: object) => { + return this.app.inject({ headers, method: 'PUT', payload, url: '/v1/subjects/identification/settings' }); + }; + + beforeAll(async () => { + adminHeaders = await login('admin'); + const group = await this.app.inject({ + headers: adminHeaders, + method: 'POST', + payload: { name: `Identification ${randomUUID()}`, type: 'RESEARCH' }, + url: '/v1/groups' + }); + expect(group.statusCode).toBe(201); + groupId = group.json<{ id: string }>().id; + const username = `identification-${randomUUID()}`; + const user = await this.app.inject({ + headers: adminHeaders, + method: 'POST', + payload: { + basePermissionLevel: 'STANDARD', + firstName: 'Identification', + groupIds: [groupId], + lastName: 'User', + password: PASSWORD, + username + }, + url: '/v1/users' + }); + expect(user.statusCode).toBe(201); + standardHeaders = await login(username); + }); + + describe('before any definition', () => { + it('should report no definition, unlocked', async () => { + await expect(getSettings(adminHeaders)).resolves.toStrictEqual({ + customFields: null, + isCustomFieldsLocked: false + }); + }); + }); + + describe('PUT /v1/subjects/identification/settings', () => { + it('should refuse anyone but an administrator', async () => { + expect((await putSettings(standardHeaders, { customFields: definition })).statusCode).toBe(403); + }); + + it('should store the definition with a salt and iteration count of the server’s choosing', async () => { + const response = await putSettings(adminHeaders, { customFields: definition }); + expect(response.statusCode).toBe(200); + const { customFields } = response.json(); + expect(customFields).toMatchObject({ ...definition, iterations: 600_000 }); + expect(customFields?.salt).toMatch(/^[0-9a-f]{64}$/); + }); + }); + + describe('GET /v1/subjects/identification/settings', () => { + it('should serve the definition, salt included, to a user who only reads subjects', async () => { + const settings = await getSettings(standardHeaders); + expect(settings.customFields?.salt).toMatch(/^[0-9a-f]{64}$/); + }); + + it('should never put the salt on the public setup route', async () => { + const { customFields } = await getSettings(adminHeaders); + const setup = await this.app.inject({ method: 'GET', url: '/v1/setup' }); + expect(setup.body).not.toContain(customFields!.salt); + }); + }); + + describe('once a subject has been identified with the fields', () => { + let salt: string; + + beforeAll(async () => { + salt = (await getSettings(adminHeaders)).customFields!.salt; + const session = await this.app.inject({ + headers: standardHeaders, + method: 'POST', + payload: { + date: new Date(), + groupId, + subjectData: { id: `cf_${'0'.repeat(64)}` }, + type: 'IN_PERSON' + }, + url: '/v1/sessions' + }); + expect(session.statusCode).toBe(201); + }); + + it('should report the definition locked', async () => { + await expect(getSettings(standardHeaders)).resolves.toMatchObject({ isCustomFieldsLocked: true }); + }); + + it('should refuse to remove the definition', async () => { + expect((await putSettings(adminHeaders, { customFields: null })).statusCode).toBe(409); + }); + + it('should refuse to change the number of fields', async () => { + const fewer = { ...definition, fields: definition.fields.slice(0, 1) }; + expect((await putSettings(adminHeaders, { customFields: fewer })).statusCode).toBe(409); + }); + + it('should still accept corrected labels and patterns, keeping the salt', async () => { + const corrected = { + fields: definition.fields.map((field) => ({ ...field, pattern: '[A-Z0-9]+' })), + label: { en: 'Mouse information' } + }; + const response = await putSettings(adminHeaders, { customFields: corrected }); + expect(response.statusCode).toBe(200); + expect(response.json().customFields).toMatchObject({ ...corrected, salt }); + }); + }); +}); diff --git a/packages/schemas/package.json b/packages/schemas/package.json index 23b394def..853208855 100644 --- a/packages/schemas/package.json +++ b/packages/schemas/package.json @@ -20,6 +20,7 @@ "./setup": "./src/setup/setup.ts", "./storage": "./src/storage/storage.ts", "./subject": "./src/subject/subject.ts", + "./subject-identification": "./src/subject-identification/subject-identification.ts", "./summary": "./src/summary/summary.ts", "./user": "./src/user/user.ts" }, diff --git a/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts b/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts new file mode 100644 index 000000000..c8ba6f72e --- /dev/null +++ b/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts @@ -0,0 +1,78 @@ +import { describe, expect, it } from 'vitest'; + +import { + $UpdateSubjectIdentificationSettingsData, + compileCustomFieldPattern, + CUSTOM_FIELDS_MAX_FIELD_COUNT +} from '../subject-identification.js'; + +const field = (pattern = '[A-Z]{2}[0-9]+') => ({ label: { en: 'Animal ID' }, pattern }); + +const update = ( + fields: { [key: string]: unknown }[], + label: { [key: string]: unknown } = { en: 'Animal information' } +) => { + return $UpdateSubjectIdentificationSettingsData.safeParse({ customFields: { fields, label } }); +}; + +describe('$UpdateSubjectIdentificationSettingsData', () => { + it('should accept a definition of labelled fields with valid patterns', () => { + expect(update([field(), field('\\p{L}+')]).success).toBe(true); + }); + + it('should accept removing the definition', () => { + expect($UpdateSubjectIdentificationSettingsData.safeParse({ customFields: null }).success).toBe(true); + }); + + it('should reject a definition with no field, which would give every subject the same id', () => { + expect(update([]).success).toBe(false); + }); + + it('should reject more fields than the limit', () => { + expect(update(Array.from({ length: CUSTOM_FIELDS_MAX_FIELD_COUNT + 1 }, () => field())).success).toBe(false); + }); + + it('should reject a pattern that does not compile', () => { + expect(update([field('[A-Z')]).success).toBe(false); + }); + + it('should reject a pattern that compiles without the u flag but not with it, since it is tested with the flag', () => { + expect(() => new RegExp('\\-')).not.toThrow(); + expect(update([field('\\-')]).success).toBe(false); + }); + + it('should reject a method label with no content in any language', () => { + expect(update([field()], { en: ' ' }).success).toBe(false); + }); + + it('should reject a field label with no content in any language', () => { + expect(update([{ label: { fr: '' }, pattern: '.+' }]).success).toBe(false); + }); + + it('should ignore a salt or iteration count sent by the client, since only the server sets them', () => { + const result = $UpdateSubjectIdentificationSettingsData.parse({ + customFields: { fields: [field()], iterations: 1, label: { en: 'Animal information' }, salt: '00' } + }); + expect(result.customFields).not.toHaveProperty('salt'); + expect(result.customFields).not.toHaveProperty('iterations'); + }); +}); + +describe('compileCustomFieldPattern', () => { + it('should match only the whole value, so a pattern cannot accept a value by matching part of it', () => { + const pattern = compileCustomFieldPattern('[0-9]{3}'); + expect(pattern.test('123')).toBe(true); + expect(pattern.test('A123')).toBe(false); + expect(pattern.test('1234')).toBe(false); + }); + + it('should keep an alternation inside the anchors', () => { + const pattern = compileCustomFieldPattern('AB|CD'); + expect(pattern.test('ABX')).toBe(false); + expect(pattern.test('CD')).toBe(true); + }); + + it('should read Unicode property escapes', () => { + expect(compileCustomFieldPattern('\\p{L}+').test('ÉLAN')).toBe(true); + }); +}); diff --git a/packages/schemas/src/subject-identification/subject-identification.ts b/packages/schemas/src/subject-identification/subject-identification.ts new file mode 100644 index 000000000..31fb93e29 --- /dev/null +++ b/packages/schemas/src/subject-identification/subject-identification.ts @@ -0,0 +1,85 @@ +import { z } from 'zod/v4'; + +import { $AuthoredLocalizedString, $LocalizedString } from '../core/core.js'; + +// ── Internal helpers (must precede all exports for import/exports-last) ─────── + +const CUSTOM_FIELDS_MAX_FIELD_COUNT = 10; + +const CUSTOM_FIELD_MAX_VALUE_LENGTH = 200; + +/** + * A field's pattern must accept the whole normalized value, never a part of it, and is read with + * the `u` flag so a class like `\p{L}` means what it says. Saving a pattern compiles it this same + * way, so a pattern that is stored is one this can compile. + */ +function compileCustomFieldPattern(pattern: string): RegExp { + return new RegExp(`^(?:${pattern})$`, 'u'); +} + +function isCompilableCustomFieldPattern(pattern: string) { + try { + compileCustomFieldPattern(pattern); + return true; + } catch { + return false; + } +} + +const $CustomIdentificationField = z.object({ + description: $LocalizedString.nullish(), + label: $AuthoredLocalizedString, + pattern: z.string().min(1).refine(isCompilableCustomFieldPattern, 'Must be a valid regular expression'), + patternErrorMessage: $LocalizedString.nullish() +}); + +// Every field is required, so a subject has exactly one id; an optional field would give it two. +const $CustomFieldsDefinitionData = z.object({ + fields: z.array($CustomIdentificationField).min(1).max(CUSTOM_FIELDS_MAX_FIELD_COUNT), + label: $AuthoredLocalizedString +}); + +// The server adds the salt and the iteration count when a definition is first saved; no client +// supplies either. +const $CustomFieldsDefinition = $CustomFieldsDefinitionData.extend({ + iterations: z.number().int().positive(), + salt: z.string() +}); + +const $SubjectIdentificationSettings = z.object({ + customFields: $CustomFieldsDefinition.nullable(), + /** Once a subject has an id derived from the fields, their number and order can never change. */ + isCustomFieldsLocked: z.boolean() +}); + +const $UpdateSubjectIdentificationSettingsData = z.object({ + customFields: $CustomFieldsDefinitionData.nullable() +}); + +type CustomIdentificationField = z.infer; + +type CustomFieldsDefinitionData = z.infer; + +type CustomFieldsDefinition = z.infer; + +type SubjectIdentificationSettings = z.infer; + +type $UpdateSubjectIdentificationSettingsData = z.infer; + +export { + $CustomFieldsDefinition, + $CustomFieldsDefinitionData, + $CustomIdentificationField, + $SubjectIdentificationSettings, + $UpdateSubjectIdentificationSettingsData, + compileCustomFieldPattern, + CUSTOM_FIELD_MAX_VALUE_LENGTH, + CUSTOM_FIELDS_MAX_FIELD_COUNT +}; + +export type { + CustomFieldsDefinition, + CustomFieldsDefinitionData, + CustomIdentificationField, + SubjectIdentificationSettings +}; diff --git a/packages/subject-utils/src/index.ts b/packages/subject-utils/src/index.ts index 9ec5985ed..e0009fbf0 100644 --- a/packages/subject-utils/src/index.ts +++ b/packages/subject-utils/src/index.ts @@ -14,7 +14,7 @@ const PERSONAL_INFO_SUBJECT_ID_PATTERN = /^[0-9a-f]{64}$/; const CUSTOM_FIELDS_SUBJECT_ID_PREFIX = 'cf_'; -const CUSTOM_FIELDS_SUBJECT_ID_PATTERN = /^cf_[0-9a-f]{64}$/; +const CUSTOM_FIELDS_SUBJECT_ID_PATTERN = new RegExp(`^${CUSTOM_FIELDS_SUBJECT_ID_PREFIX}[0-9a-f]{64}$`); const CUSTOM_FIELDS_SALT_PATTERN = /^[0-9a-f]{64}$/; @@ -149,4 +149,6 @@ export async function deriveCustomFieldsSubjectId( return CUSTOM_FIELDS_SUBJECT_ID_PREFIX + encodeLowercaseHex(derivedBits); } +export { CUSTOM_FIELDS_SUBJECT_ID_PREFIX }; + export { removeSubjectIdScope } from '@opendatacapture/runtime-internal'; From 4b575bd828b581687893d4be8b6b6d0dee4e17e7 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 11:39:04 -0500 Subject: [PATCH 16/19] feat: identify subjects by the fields an administrator defines Once an administrator has defined custom identifying fields, Start Session and the data hub's subject lookup offer them as a third identification method, CUSTOM_FIELDS, under the administrator's label. The forms ask for every field, test each pattern against the normalized value, derive the id in the browser (cf_ and the PBKDF2 digest) and send only that id with the optional date of birth and sex; no name and no typed value leaves the browser. Once every field is valid, Start Session looks the subject up by the derived id and fills in and locks what they record, as it does for a custom id. A group can make the method its default, a cf_ id is classified by its shape and never scoped to a group, and the session card shortens it to the group's display length. Refs #1546 Co-Authored-By: Claude Opus 5.5 --- apps/api/prisma/schema.prisma | 1 + .../IdentificationForm/IdentificationForm.tsx | 71 +++++++---- .../__tests__/IdentificationForm.test.tsx | 48 +++++++- apps/web/src/components/Sidebar/Sidebar.tsx | 16 ++- .../Sidebar/__tests__/Sidebar.test.tsx | 26 +++- .../StartSessionForm/StartSessionForm.tsx | 92 +++++++++----- .../__tests__/StartSessionForm.test.tsx | 104 +++++++++++++++- .../useCustomIdentificationFields.test.ts | 112 +++++++++++++++++ ...SubjectIdentificationSettingsQuery.test.ts | 47 +++++++ .../hooks/useCustomIdentificationFields.ts | 115 ++++++++++++++++++ .../useSubjectIdentificationSettingsQuery.ts | 19 +++ .../routes/_app/datahub/subjects/index.tsx | 4 +- .../_app/group/__tests__/manage.test.tsx | 68 +++++++++-- apps/web/src/routes/_app/group/manage.tsx | 44 +++++-- .../session/__tests__/start-session.test.tsx | 28 ++++- .../src/routes/_app/session/start-session.tsx | 7 ++ .../3.4-how-to-get-started-with-odc.mdx | 2 +- .../4.2-hash-based-identification.md | 23 ++++ packages/schemas/src/subject/subject.ts | 2 +- packages/subject-utils/AGENTS.md | 2 +- .../subject-utils/src/__tests__/index.test.ts | 29 ++--- packages/subject-utils/src/index.ts | 17 ++- .../pages/_app/session/start-session.page.ts | 11 ++ testing/src/specs/custom-fields.spec.ts | 81 ++++++++++++ testing/src/specs/datahub.spec.ts | 2 +- testing/src/support/api-client.ts | 15 +++ 26 files changed, 865 insertions(+), 121 deletions(-) create mode 100644 apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts create mode 100644 apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts create mode 100644 apps/web/src/hooks/useCustomIdentificationFields.ts create mode 100644 apps/web/src/hooks/useSubjectIdentificationSettingsQuery.ts create mode 100644 testing/src/specs/custom-fields.spec.ts diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index 754fa03b8..c568d757c 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -99,6 +99,7 @@ enum GroupType { enum SubjectIdentificationMethod { CUSTOM_ID PERSONAL_INFO + CUSTOM_FIELDS } type GroupSettings { diff --git a/apps/web/src/components/IdentificationForm/IdentificationForm.tsx b/apps/web/src/components/IdentificationForm/IdentificationForm.tsx index 38b16bbe6..f86402ad7 100644 --- a/apps/web/src/components/IdentificationForm/IdentificationForm.tsx +++ b/apps/web/src/components/IdentificationForm/IdentificationForm.tsx @@ -2,11 +2,13 @@ import { Form } from '@douglasneuroinformatics/libui/components'; import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; -import { $Sex, $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import { $Sex } from '@opendatacapture/schemas/subject'; import { encodeScopedSubjectId, generateSubjectHash } from '@opendatacapture/subject-utils'; import type { Promisable } from 'type-fest'; import { z } from 'zod/v4'; +import { useCustomIdentificationFields } from '@/hooks/useCustomIdentificationFields'; +import { useSubjectIdentificationSettingsQuery } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useAppStore } from '@/store'; type IdentificationFormProps = { @@ -16,6 +18,14 @@ type IdentificationFormProps = { export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { const currentGroup = useAppStore((store) => store.currentGroup); const { t } = useTranslation(); + const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); + const customFields = useCustomIdentificationFields(subjectIdentificationSettingsQuery.data.customFields); + + const methodOptions: { [method: string]: string } = { + CUSTOM_ID: t('common.customIdentifier'), + PERSONAL_INFO: t('common.personalInfo'), + ...(customFields.label === null ? {} : { CUSTOM_FIELDS: customFields.label }) + }; return ( { { title: t('common.identificationMethod'), fields: { - identificationMethod: { + subjectIdentificationMethod: { kind: 'string', label: 'Method', - options: { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo') - }, + options: methodOptions, variant: 'select' } } @@ -41,9 +48,9 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { fields: { id: { kind: 'dynamic', - deps: ['identificationMethod'], - render({ identificationMethod }) { - return identificationMethod === 'CUSTOM_ID' + deps: ['subjectIdentificationMethod'], + render({ subjectIdentificationMethod }) { + return subjectIdentificationMethod === 'CUSTOM_ID' ? { kind: 'string', label: t('common.identifier'), @@ -52,11 +59,12 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { : null; } }, + ...customFields.formFields, firstName: { kind: 'dynamic', - deps: ['identificationMethod'], - render({ identificationMethod }) { - return identificationMethod === 'PERSONAL_INFO' + deps: ['subjectIdentificationMethod'], + render({ subjectIdentificationMethod }) { + return subjectIdentificationMethod === 'PERSONAL_INFO' ? { description: t('common.subjectIdentification.firstName.description'), kind: 'string', @@ -68,9 +76,9 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { }, lastName: { kind: 'dynamic', - deps: ['identificationMethod'], - render({ identificationMethod }) { - return identificationMethod === 'PERSONAL_INFO' + deps: ['subjectIdentificationMethod'], + render({ subjectIdentificationMethod }) { + return subjectIdentificationMethod === 'PERSONAL_INFO' ? { description: t('common.subjectIdentification.lastName.description'), kind: 'string', @@ -82,9 +90,9 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { }, dateOfBirth: { kind: 'dynamic', - deps: ['identificationMethod'], - render({ identificationMethod }) { - return identificationMethod === 'PERSONAL_INFO' + deps: ['subjectIdentificationMethod'], + render({ subjectIdentificationMethod }) { + return subjectIdentificationMethod === 'PERSONAL_INFO' ? { kind: 'date', label: t('core.identificationData.dateOfBirth.label') @@ -94,9 +102,9 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { }, sex: { kind: 'dynamic', - deps: ['identificationMethod'], - render({ identificationMethod }) { - return identificationMethod === 'PERSONAL_INFO' + deps: ['subjectIdentificationMethod'], + render({ subjectIdentificationMethod }) { + return subjectIdentificationMethod === 'PERSONAL_INFO' ? { description: t('core.identificationData.sex.description'), kind: 'string', @@ -115,20 +123,21 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { ]} data-testid="identification-form" initialValues={{ - identificationMethod: currentGroup?.settings.defaultIdentificationMethod ?? 'PERSONAL_INFO' + subjectIdentificationMethod: currentGroup?.settings.defaultIdentificationMethod ?? 'PERSONAL_INFO' }} submitBtnLabel={t('core.submit')} validationSchema={z .object({ firstName: z.string().min(1).optional(), lastName: z.string().min(1).optional(), - identificationMethod: $SubjectIdentificationMethod, + subjectIdentificationMethod: z.enum(Object.keys(methodOptions)), id: z.string().min(1).optional(), dateOfBirth: z.date().optional(), - sex: $Sex.optional() + sex: $Sex.optional(), + ...customFields.shape }) .superRefine((val, ctx) => { - if (val.identificationMethod === 'CUSTOM_ID') { + if (val.subjectIdentificationMethod === 'CUSTOM_ID') { if (!val.id) { ctx.addIssue({ code: z.ZodIssueCode.custom, @@ -136,6 +145,10 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { path: ['id'] }); } + } else if (val.subjectIdentificationMethod === 'CUSTOM_FIELDS') { + for (const [key, message] of Object.entries(customFields.findErrors(val))) { + ctx.addIssue({ code: z.ZodIssueCode.custom, message, path: [key] }); + } } else { const requiredKeys = ['firstName', 'lastName', 'sex', 'dateOfBirth'] as const; for (const key of requiredKeys) { @@ -149,8 +162,12 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { } } })} - onSubmit={async ({ id, firstName, lastName, dateOfBirth, sex }) => { - if (!id) { + onSubmit={async (values) => { + const { firstName, lastName, dateOfBirth, sex } = values; + let { id } = values; + if (values.subjectIdentificationMethod === 'CUSTOM_FIELDS') { + id = await customFields.deriveSubjectId(values); + } else if (!id) { id = await generateSubjectHash({ firstName: firstName!, lastName: lastName!, diff --git a/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx b/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx index 483571bb8..2ddc6dd1d 100644 --- a/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx +++ b/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx @@ -1,6 +1,8 @@ import { i18n } from '@douglasneuroinformatics/libui/i18n'; import type { Group } from '@opendatacapture/schemas/group'; import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; +import { deriveCustomFieldsSubjectId } from '@opendatacapture/subject-utils'; import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; @@ -15,6 +17,15 @@ const store = vi.hoisted(() => { const subjectUtils = vi.hoisted(() => ({ generateSubjectHash: vi.fn() })); +const settings = vi.hoisted(() => { + const state: { customFields: CustomFieldsDefinition | null } = { customFields: null }; + return state; +}); + +vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', () => ({ + useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: settings.customFields } }) +})); + vi.mock('@/store', () => ({ useAppStore: vi.fn((selector: (state: typeof store) => unknown) => selector(store)) })); @@ -71,6 +82,7 @@ describe('IdentificationForm', () => { beforeEach(() => { i18n.changeLanguage('en'); store.currentGroup = null; + settings.customFields = null; subjectUtils.generateSubjectHash.mockResolvedValue('subject-hash'); }); @@ -119,7 +131,7 @@ describe('IdentificationForm', () => { it('should scope a custom identifier to the root group when no group is selected', async () => { const onSubmit = renderForm(); - setField('identificationMethod', 'CUSTOM_ID'); + setField('subjectIdentificationMethod', 'CUSTOM_ID'); setField('id', 'subject-7'); submit(); await waitFor(() => expect(onSubmit).toHaveBeenCalledWith({ id: 'root$subject-7' })); @@ -147,4 +159,38 @@ describe('IdentificationForm', () => { sex: 'FEMALE' }); }); + + describe('with custom fields', () => { + beforeEach(() => { + settings.customFields = { + fields: [{ label: { en: 'Animal ID' }, pattern: '[A-Z]{2}[0-9]+' }], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) + }; + store.currentGroup = createGroup('CUSTOM_FIELDS'); + }); + + it('should ask only for the fields the administrator defined', () => { + renderForm(); + expect(field('customField0')).toBeTruthy(); + expect(['id', 'firstName', 'lastName', 'dateOfBirth', 'sex'].some((name) => field(name))).toBe(false); + }); + + it('should identify the subject by the id derived from the fields, as Start Session does', async () => { + const onSubmit = renderForm(); + setField('customField0', 'ab-12'); + submit(); + const id = await deriveCustomFieldsSubjectId(['ab-12'], { iterations: 1000, salt: '0f'.repeat(32) }); + await waitFor(() => expect(onSubmit).toHaveBeenCalledWith({ id })); + }); + + it('should refuse a value the field rejects', async () => { + const onSubmit = renderForm(); + setField('customField0', '12'); + submit(); + await waitFor(() => expect(fieldsWithErrors()).toEqual(['customField0'])); + expect(onSubmit).not.toHaveBeenCalled(); + }); + }); }); diff --git a/apps/web/src/components/Sidebar/Sidebar.tsx b/apps/web/src/components/Sidebar/Sidebar.tsx index 74e90ff52..faf395df5 100644 --- a/apps/web/src/components/Sidebar/Sidebar.tsx +++ b/apps/web/src/components/Sidebar/Sidebar.tsx @@ -2,7 +2,11 @@ import { toBasicISOString, toLowerCase } from '@douglasneuroinformatics/libjs'; import { ThemeToggle } from '@douglasneuroinformatics/libui/components'; import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; import { Branding, LanguageToggle } from '@opendatacapture/react-core'; -import { isSubjectWithPersonalInfo, removeSubjectIdScope } from '@opendatacapture/subject-utils'; +import { + inferSubjectIdentificationMethod, + isSubjectWithPersonalInfo, + removeSubjectIdScope +} from '@opendatacapture/subject-utils'; import { useLocation } from '@tanstack/react-router'; import { AnimatePresence, motion } from 'motion/react'; @@ -21,11 +25,19 @@ export const Sidebar = () => { const isGroupSwitcherVisible = useIsGroupSwitcherVisible(); const navItems = useNavItems(); const currentSession = useAppStore((store) => store.currentSession); + const currentGroup = useAppStore((store) => store.currentGroup); const location = useLocation(); const { activeLanguages } = useSetupStateQuery().data; const { t } = useTranslation(); + // A custom-fields id is a 67-character digest, shortened as the datahub shortens it. + const formatSubjectId = (subjectId: string) => { + return inferSubjectIdentificationMethod(subjectId) === 'CUSTOM_FIELDS' + ? subjectId.slice(0, currentGroup?.settings.subjectIdDisplayLength ?? 9) + : removeSubjectIdScope(subjectId); + }; + return (
{

{t( { en: 'ID: {}', es: 'ID: {}', fr: 'ID : {}' }, - { args: [removeSubjectIdScope(currentSession.subject!.id)] } + { args: [formatSubjectId(currentSession.subject!.id)] } )}

diff --git a/apps/web/src/components/Sidebar/__tests__/Sidebar.test.tsx b/apps/web/src/components/Sidebar/__tests__/Sidebar.test.tsx index 0a2343340..2d56edf5f 100644 --- a/apps/web/src/components/Sidebar/__tests__/Sidebar.test.tsx +++ b/apps/web/src/components/Sidebar/__tests__/Sidebar.test.tsx @@ -13,6 +13,7 @@ import { Sidebar } from '../Sidebar'; import '@/services/i18n'; type MockStore = { + currentGroup: null | { settings: { subjectIdDisplayLength?: null | number } }; currentSession: null | Session; endSession: () => void; groupSwitcherPosition: GroupSwitcherPosition; @@ -26,7 +27,12 @@ type Mocks = { }; const mocks = vi.hoisted((): Mocks => { - const store: MockStore = { currentSession: null, endSession: vi.fn(), groupSwitcherPosition: 'sidebar' }; + const store: MockStore = { + currentGroup: null, + currentSession: null, + endSession: vi.fn(), + groupSwitcherPosition: 'sidebar' + }; return { isGroupSwitcherVisible: false, navigate: vi.fn(), navItems: [], store }; }); @@ -95,6 +101,7 @@ describe('Sidebar', () => { beforeEach(() => { mocks.isGroupSwitcherVisible = false; mocks.navItems = [globalItems, sessionItems]; + mocks.store.currentGroup = null; mocks.store.currentSession = null; mocks.store.groupSwitcherPosition = 'sidebar'; mocks.navigate.mockReset().mockResolvedValue(undefined); @@ -206,4 +213,21 @@ describe('Sidebar', () => { render(); expect(sessionInfo()).toBe('ID: abc'); }); + + describe('with a subject identified by custom fields', () => { + const customFieldsId = `cf_${'a1'.repeat(32)}`; + + it("should shorten the id to the group's display length, as the datahub shows it", () => { + mocks.store.currentGroup = { settings: { subjectIdDisplayLength: 12 } }; + mocks.store.currentSession = sessionFor(subject({ id: customFieldsId })); + render(); + expect(sessionInfo()).toBe(`ID: ${customFieldsId.slice(0, 12)}`); + }); + + it('should shorten the id to nine characters when the group sets no display length', () => { + mocks.store.currentSession = sessionFor(subject({ id: customFieldsId })); + render(); + expect(sessionInfo()).toBe('ID: cf_a1a1a1'); + }); + }); }); diff --git a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx index 855cf056c..05f3015a0 100644 --- a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx +++ b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx @@ -10,12 +10,14 @@ import { DEFAULT_GROUP_NAME } from '@opendatacapture/schemas/core'; import type { Group } from '@opendatacapture/schemas/group'; import { $SessionType } from '@opendatacapture/schemas/session'; import type { $CreateSessionData } from '@opendatacapture/schemas/session'; -import { $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; -import type { Sex, SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import type { Sex } from '@opendatacapture/schemas/subject'; +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; import { encodeScopedSubjectId, generateSubjectHash } from '@opendatacapture/subject-utils'; import type { Promisable } from 'type-fest'; import { z } from 'zod/v4'; +import { useCustomIdentificationFields } from '@/hooks/useCustomIdentificationFields'; +import type { CustomFieldsFormData } from '@/hooks/useCustomIdentificationFields'; import { useSubjectDemographicsLookup } from '@/hooks/useSubjectDemographicsLookup'; import { getValueForLanguage } from '@/utils/language'; @@ -27,24 +29,19 @@ type StartSessionFormValues = FormTypes.PartialData; type AutofilledDemographics = Pick; -/** Empty unless a custom identifier is in use, so switching method clears what it filled in. */ -const selectedCustomId = (values: StartSessionFormValues) => { - return values.subjectIdentificationMethod === 'CUSTOM_ID' ? (values.subjectId ?? '') : ''; -}; - -type StartSessionFormData = { +type StartSessionFormData = CustomFieldsFormData & { sessionDate?: Date; sessionType: 'IN_PERSON' | 'RETROSPECTIVE'; subjectDateOfBirth?: Date; subjectFirstName?: string; subjectId?: string; - subjectIdentificationMethod: SubjectIdentificationMethod; subjectLastName?: string; subjectSex?: Sex; }; type StartSessionFormProps = { currentGroup: Group | null; + customFieldsDefinition: CustomFieldsDefinition | null; customSubjectIds: string[]; initialValues?: FormTypes.PartialNullableData; onSubmit: (data: $CreateSessionData) => Promisable; @@ -54,6 +51,7 @@ type StartSessionFormProps = { export const StartSessionForm = ({ currentGroup, + customFieldsDefinition, customSubjectIds, username, initialValues, @@ -63,21 +61,54 @@ export const StartSessionForm = ({ const { resolvedLanguage, t } = useTranslation(); const lookupDemographics = useSubjectDemographicsLookup(); const [autofilled, setAutofilled] = useState({}); - const latestCustomId = useRef(''); + const latestIdentity = useRef(''); + const customFields = useCustomIdentificationFields(customFieldsDefinition); + + const methodOptions: { [method: string]: string } = { + CUSTOM_ID: t('common.customIdentifier'), + PERSONAL_INFO: t('common.personalInfo'), + ...(customFields.label === null ? {} : { CUSTOM_FIELDS: customFields.label }) + }; const scopeCustomId = (customId: string) => { return encodeScopedSubjectId(customId, { groupName: currentGroup?.name ?? DEFAULT_GROUP_NAME }); }; + /** + * What identifies the subject so far, if enough to look them up: empty for personal information, + * an incomplete entry or a method switch, so either of the last two clears what was filled in. + */ + const selectIdentity = (values: StartSessionFormValues) => { + if (values.subjectIdentificationMethod === 'CUSTOM_ID') { + return values.subjectId ? `CUSTOM_ID:${values.subjectId}` : ''; + } else if ( + values.subjectIdentificationMethod === 'CUSTOM_FIELDS' && + Object.keys(customFields.findErrors(values)).length === 0 + ) { + return `CUSTOM_FIELDS:${JSON.stringify(customFields.orderValues(values))}`; + } + return ''; + }; + + /** The stored id of a subject who may already exist, or null when there can be none yet. */ + const findExistingSubjectId = async (values: StartSessionFormValues) => { + if (values.subjectIdentificationMethod === 'CUSTOM_FIELDS') { + return customFields.deriveSubjectId(values); + } + // A custom id absent from the group's suggestions belongs to no subject, so it is not looked up. + return values.subjectId && customSubjectIds.includes(values.subjectId) ? scopeCustomId(values.subjectId) : null; + }; + const autofillExistingSubject = async ( values: StartSessionFormValues, setValues: Dispatch> ) => { - const customId = selectedCustomId(values); - latestCustomId.current = customId; - const demographics = customSubjectIds.includes(customId) ? await lookupDemographics(scopeCustomId(customId)) : null; + const identity = selectIdentity(values); + latestIdentity.current = identity; + const subjectId = identity ? await findExistingSubjectId(values) : null; + const demographics = subjectId ? await lookupDemographics(subjectId) : null; // A slower lookup for an identifier the user has since moved on from must not overwrite the newer one. - if (latestCustomId.current !== customId) { + if (latestIdentity.current !== identity) { return; } const next: AutofilledDemographics = { @@ -106,10 +137,7 @@ export const StartSessionForm = ({ subjectIdentificationMethod: { kind: 'string', label: 'Method', - options: { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo') - }, + options: methodOptions, variant: 'select' } } @@ -132,6 +160,7 @@ export const StartSessionForm = ({ : null; } }, + ...customFields.formFields, subjectFirstName: { kind: 'dynamic', deps: ['subjectIdentificationMethod'], @@ -213,13 +242,13 @@ export const StartSessionForm = ({ submitBtnLabel={t('core.submit')} subscribe={{ onChange: autofillExistingSubject, - selector: selectedCustomId + selector: selectIdentity }} validationSchema={z .object({ subjectFirstName: z.string().optional(), subjectLastName: z.string().optional(), - subjectIdentificationMethod: $SubjectIdentificationMethod, + subjectIdentificationMethod: z.enum(Object.keys(methodOptions)), // Every check on the identifier and the two dates lives in the refinement below: zod v4 // omits an optional property that failed its own checks from the value it hands the // refinement, which then reads the field as missing and adds a contradictory required-field @@ -228,7 +257,8 @@ export const StartSessionForm = ({ subjectDateOfBirth: z.date().optional(), subjectSex: z.enum(['MALE', 'FEMALE']).optional(), sessionType: $SessionType.exclude(['REMOTE']), - sessionDate: z.date().optional() + sessionDate: z.date().optional(), + ...customFields.shape }) .superRefine((val, ctx) => { if (val.sessionType === 'RETROSPECTIVE') { @@ -287,6 +317,10 @@ export const StartSessionForm = ({ console.error(err); } } + } else if (val.subjectIdentificationMethod === 'CUSTOM_FIELDS') { + for (const [key, message] of Object.entries(customFields.findErrors(val))) { + ctx.addIssue({ code: z.ZodIssueCode.custom, message, path: [key] }); + } } else { const requiredKeys = ['subjectFirstName', 'subjectLastName', 'subjectSex', 'subjectDateOfBirth'] as const; for (const key of requiredKeys) { @@ -323,16 +357,12 @@ export const StartSessionForm = ({ }); } })} - onSubmit={async ({ - sessionType, - sessionDate, - subjectId, - subjectFirstName, - subjectLastName, - subjectDateOfBirth, - subjectSex - }) => { - if (!subjectId) { + onSubmit={async (values) => { + const { sessionType, sessionDate, subjectFirstName, subjectLastName, subjectDateOfBirth, subjectSex } = values; + let { subjectId } = values; + if (values.subjectIdentificationMethod === 'CUSTOM_FIELDS') { + subjectId = await customFields.deriveSubjectId(values); + } else if (!subjectId) { subjectId = await generateSubjectHash({ firstName: subjectFirstName!, lastName: subjectLastName!, diff --git a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx index 1b4698148..1ab99513d 100644 --- a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx +++ b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx @@ -1,6 +1,7 @@ import { DEFAULT_GROUP_NAME } from '@opendatacapture/schemas/core'; import type { Group, GroupSettings } from '@opendatacapture/schemas/group'; -import { generateSubjectHash } from '@opendatacapture/subject-utils'; +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; +import { deriveCustomFieldsSubjectId, generateSubjectHash } from '@opendatacapture/subject-utils'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { act, cleanup, fireEvent, getByText, render, screen, waitFor } from '@testing-library/react'; import axios from 'axios'; @@ -34,16 +35,28 @@ const groupWithIdPattern = (idValidationRegex: string) => groupWithSettings({ id const createQueryClient = () => new QueryClient({ defaultOptions: { queries: { retry: false } } }); +const customFieldsDefinition: CustomFieldsDefinition = { + fields: [ + { label: { en: 'Animal ID' }, pattern: '[A-Z]{2}[0-9]+', patternErrorMessage: { en: 'Two letters, then digits' } }, + { label: { en: 'Cage' }, pattern: '[0-9]+' } + ], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) +}; + const renderForm = ( customSubjectIds: string[], currentGroup: Group | null = null, - method: 'CUSTOM_ID' | 'PERSONAL_INFO' = 'CUSTOM_ID', - queryClient = createQueryClient() + method: 'CUSTOM_FIELDS' | 'CUSTOM_ID' | 'PERSONAL_INFO' = 'CUSTOM_ID', + queryClient = createQueryClient(), + definition: CustomFieldsDefinition | null = null ) => { render( { it('should submit a null username when none is known, rather than an undefined one the API would reject', async () => { render( - + ); const form = screen.getByTestId('start-session-form'); @@ -431,6 +450,83 @@ describe('StartSessionForm', () => { }); }); + describe('with custom fields', () => { + const renderWithCustomFields = () => + renderForm([], null, 'CUSTOM_FIELDS', createQueryClient(), customFieldsDefinition); + + const fillCustomFields = (form: HTMLElement, values: [string, string]) => { + values.forEach((value, index) => { + fireEvent.change(form.querySelector(`[name="customField${index}"]`)!, { target: { value } }); + }); + }; + + const methodOptions = (form: HTMLElement) => { + const select = form.querySelector('select[name="subjectIdentificationMethod"]')!; + return Array.from(select.options, (option) => option.value).filter(Boolean); + }; + + const derivedId = () => deriveCustomFieldsSubjectId(['ab12', '7'], { iterations: 1000, salt: '0f'.repeat(32) }); + + it('should offer the method only once its fields are defined', () => { + expect(methodOptions(renderForm([]))).toStrictEqual(['CUSTOM_ID', 'PERSONAL_INFO']); + cleanup(); + expect(methodOptions(renderWithCustomFields())).toStrictEqual(['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS']); + }); + + it("should name the method with the administrator's label and ask for each of their fields", () => { + renderWithCustomFields(); + expect(screen.getAllByText('Animal information').length).toBeGreaterThan(0); + expect(screen.getByText('Animal ID')).toBeTruthy(); + expect(screen.getByText('Cage')).toBeTruthy(); + }); + + it('should identify the subject by the id derived from the fields, sending no name', async () => { + const form = renderWithCustomFields(); + fillCustomFields(form, ['ab12', '7']); + await submitAndSettle(form); + expect(onSubmit.mock.lastCall?.[0].subjectData).toStrictEqual({ + dateOfBirth: undefined, + firstName: undefined, + id: await derivedId(), + lastName: undefined, + sex: undefined + }); + }); + + it('should show the error of each field the values fail', async () => { + const form = renderWithCustomFields(); + fillCustomFields(form, ['12', '']); + submit(form); + await waitFor(() => { + expect(errorMessages()).toEqual([ + { field: 'customField0', message: 'Two letters, then digits' }, + { field: 'customField1', message: 'This field is required' } + ]); + }); + expect(onSubmit).not.toHaveBeenCalled(); + }); + + it('should look the subject up by the derived id once every field is valid, and fill in and lock their details', async () => { + existingSubject({ dateOfBirth: '1990-06-15', sex: 'FEMALE' }); + const form = renderWithCustomFields(); + fillCustomFields(form, ['ab12', '7']); + await waitFor(() => expect(dateOfBirthInput().disabled).toBe(true)); + expect(get).toHaveBeenCalledWith(`/v1/subjects/${await derivedId()}`, expect.anything()); + expect(sexTrigger().disabled).toBe(true); + }); + + it('should not look anyone up while a field is still invalid', async () => { + const form = renderWithCustomFields(); + fillCustomFields(form, ['12', '7']); + await act(async () => { + await new Promise((resolve) => { + setTimeout(resolve, 50); + }); + }); + expect(get).not.toHaveBeenCalled(); + }); + }); + describe('session type', () => { it('should ask for the assessment date only for a retrospective session, since an in-person one happens today', () => { const form = renderForm([]); diff --git a/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts b/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts new file mode 100644 index 000000000..285fa114b --- /dev/null +++ b/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts @@ -0,0 +1,112 @@ +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; +import { deriveCustomFieldsSubjectId } from '@opendatacapture/subject-utils'; +import { renderHook } from '@testing-library/react'; +import { describe, expect, it } from 'vitest'; +import { z } from 'zod/v4'; + +import { useCustomIdentificationFields } from '../useCustomIdentificationFields'; + +import '@/services/i18n'; + +const definition: CustomFieldsDefinition = { + fields: [ + { + description: { en: 'On the ear tag' }, + label: { en: 'Animal ID', fr: "Identifiant de l'animal" }, + pattern: '[A-Z]{2}[0-9]+', + patternErrorMessage: { en: 'Two letters, then digits' } + }, + { label: { en: 'Cage' }, pattern: '[0-9]+' } + ], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) +}; + +const renderFields = (value: CustomFieldsDefinition | null = definition) => { + return renderHook(() => useCustomIdentificationFields(value)).result.current; +}; + +describe('useCustomIdentificationFields', () => { + it('should offer no method and no field without a definition', () => { + const fields = renderFields(null); + expect(fields.label).toBeNull(); + expect(fields.formFields).toStrictEqual({}); + expect(fields.findErrors({})).toStrictEqual({}); + }); + + it("should label the method with the administrator's label", () => { + expect(renderFields().label).toBe('Animal information'); + }); + + it('should key one field per defined field, in order', () => { + expect(Object.keys(renderFields().formFields)).toStrictEqual(['customField0', 'customField1']); + expect(Object.keys(renderFields().shape)).toStrictEqual(['customField0', 'customField1']); + }); + + it('should render a field only while the method is chosen, with its label and help text', () => { + const { formFields } = renderFields(); + expect(formFields.customField0?.render({ subjectIdentificationMethod: 'CUSTOM_ID' })).toBeNull(); + expect(formFields.customField0?.render({ subjectIdentificationMethod: 'CUSTOM_FIELDS' })).toMatchObject({ + description: 'On the ear tag', + kind: 'string', + label: 'Animal ID' + }); + }); + + it('should accept a field value as an optional string, leaving every check to findErrors', () => { + const schema = z.object(renderFields().shape); + expect(schema.safeParse({}).success).toBe(true); + expect(schema.safeParse({ customField0: 1 }).success).toBe(false); + }); + + describe('findErrors', () => { + it('should require every field, since an optional field would give one subject two ids', () => { + expect(renderFields().findErrors({ customField0: 'ab12' })).toStrictEqual({ + customField1: 'This field is required' + }); + }); + + it('should test the pattern against the normalized value, so case and punctuation do not matter', () => { + expect(renderFields().findErrors({ customField0: 'ab-12', customField1: '7' })).toStrictEqual({}); + }); + + it("should show the administrator's message for a value the pattern rejects", () => { + expect(renderFields().findErrors({ customField0: '12', customField1: '7' })).toStrictEqual({ + customField0: 'Two letters, then digits' + }); + }); + + it('should name the pattern when the administrator wrote no message', () => { + expect(renderFields().findErrors({ customField0: 'ab1', customField1: 'x' })).toStrictEqual({ + customField1: 'Must match regular expression: [0-9]+' + }); + }); + + it('should refuse a value with no letter or digit, which would normalize to nothing', () => { + expect(renderFields().findErrors({ customField0: 'ab1', customField1: '--' })).toStrictEqual({ + customField1: 'Must contain at least one letter or digit' + }); + }); + + it('should refuse a value longer than 200 characters', () => { + expect(renderFields().findErrors({ customField0: 'ab1', customField1: '1'.repeat(201) })).toStrictEqual({ + customField1: 'Must be at most 200 characters' + }); + }); + }); + + it('should order the values as the fields are defined', () => { + expect(renderFields().orderValues({ customField0: 'ab1', customField1: '7' })).toStrictEqual(['ab1', '7']); + }); + + it("should derive the subject id from the values in order, with the instance's salt and iterations", async () => { + await expect(renderFields().deriveSubjectId({ customField0: 'ab1', customField1: '7' })).resolves.toBe( + await deriveCustomFieldsSubjectId(['ab1', '7'], { iterations: 1000, salt: '0f'.repeat(32) }) + ); + }); + + it('should refuse to derive an id without a definition', async () => { + await expect(renderFields(null).deriveSubjectId({})).rejects.toThrow(/without a definition/); + }); +}); diff --git a/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts b/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts new file mode 100644 index 000000000..a12840e24 --- /dev/null +++ b/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts @@ -0,0 +1,47 @@ +import type { PropsWithChildren } from 'react'; +import { createElement, Suspense } from 'react'; + +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { renderHook, waitFor } from '@testing-library/react'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +import { useSubjectIdentificationSettingsQuery } from '../useSubjectIdentificationSettingsQuery'; + +const mockAxios = vi.hoisted(() => ({ get: vi.fn(), isAxiosError: vi.fn(() => false) })); + +vi.mock('axios', () => ({ default: mockAxios })); + +const settings = { + customFields: { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 600_000, + label: { en: 'Animal information' }, + salt: 'ab'.repeat(32) + }, + isCustomFieldsLocked: false +}; + +function renderSettingsQuery() { + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + const wrapper = ({ children }: PropsWithChildren) => { + return createElement( + QueryClientProvider, + { client: queryClient }, + createElement(Suspense, { fallback: null }, children) + ); + }; + return renderHook(() => useSubjectIdentificationSettingsQuery(), { wrapper }); +} + +describe('useSubjectIdentificationSettingsQuery', () => { + beforeEach(() => { + vi.clearAllMocks(); + mockAxios.get.mockResolvedValue({ data: settings }); + }); + + it('should request the settings and parse them at the boundary', async () => { + const { result } = renderSettingsQuery(); + await waitFor(() => expect(result.current?.data).toStrictEqual(settings)); + expect(mockAxios.get).toHaveBeenCalledWith('/v1/subjects/identification/settings'); + }); +}); diff --git a/apps/web/src/hooks/useCustomIdentificationFields.ts b/apps/web/src/hooks/useCustomIdentificationFields.ts new file mode 100644 index 000000000..78d7ccce2 --- /dev/null +++ b/apps/web/src/hooks/useCustomIdentificationFields.ts @@ -0,0 +1,115 @@ +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { FormTypes } from '@opendatacapture/runtime-core'; +import type { LocalizedString } from '@opendatacapture/schemas/core'; +import { + compileCustomFieldPattern, + CUSTOM_FIELD_MAX_VALUE_LENGTH +} from '@opendatacapture/schemas/subject-identification'; +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; +import { deriveCustomFieldsSubjectId, normalizeCustomFieldValue } from '@opendatacapture/subject-utils'; +import { z } from 'zod/v4'; + +import { getValueForLanguage } from '@/utils/language'; + +const customFieldKey = (index: number): CustomFieldKey => `customField${index}`; + +export type CustomFieldKey = `customField${number}`; + +/** The part of an identification form the custom fields read: their values and the method chosen. */ +export type CustomFieldsFormData = { [K in CustomFieldKey]?: string } & { subjectIdentificationMethod: string }; + +export type CustomFieldErrors = { [K in CustomFieldKey]?: string }; + +/** + * The fields an administrator defined for identifying subjects, ready to drop into a libui `Form` + * whose `subjectIdentificationMethod` can be `CUSTOM_FIELDS`. Every field is required, and each is + * judged on its normalized value, which is what the id is derived from. + */ +export function useCustomIdentificationFields(definition: CustomFieldsDefinition | null) { + const { resolvedLanguage, t } = useTranslation(); + const fields = definition?.fields ?? []; + + const localize = (value: LocalizedString | null | undefined) => { + return value ? getValueForLanguage(value, resolvedLanguage) : undefined; + }; + + const formFields: { [K in CustomFieldKey]?: FormTypes.DynamicField } = Object.fromEntries( + fields.map((field, index) => [ + customFieldKey(index), + { + deps: ['subjectIdentificationMethod'], + kind: 'dynamic', + render: ({ subjectIdentificationMethod }) => { + return subjectIdentificationMethod === 'CUSTOM_FIELDS' + ? { + description: localize(field.description), + kind: 'string', + label: localize(field.label) ?? '', + variant: 'input' + } + : null; + } + } satisfies FormTypes.DynamicField + ]) + ); + + // Every check lives in `findErrors`, run from the form's refinement: zod v4 drops a property that + // failed its own checks from the value it hands a refinement. + const shape: { [K in CustomFieldKey]: z.ZodOptional } = Object.fromEntries( + fields.map((_, index) => [customFieldKey(index), z.string().optional()]) + ); + + const findErrors = (values: { [K in CustomFieldKey]?: string }): CustomFieldErrors => { + const errors: CustomFieldErrors = {}; + fields.forEach((field, index) => { + const key = customFieldKey(index); + const value = values[key]; + if (!value) { + errors[key] = t('core.form.requiredField'); + } else if (value.length > CUSTOM_FIELD_MAX_VALUE_LENGTH) { + errors[key] = t({ + en: `Must be at most ${CUSTOM_FIELD_MAX_VALUE_LENGTH} characters`, + es: `Debe tener como máximo ${CUSTOM_FIELD_MAX_VALUE_LENGTH} caracteres`, + fr: `Doit comporter au plus ${CUSTOM_FIELD_MAX_VALUE_LENGTH} caractères` + }); + } else if (!normalizeCustomFieldValue(value)) { + errors[key] = t({ + en: 'Must contain at least one letter or digit', + es: 'Debe contener al menos una letra o un dígito', + fr: 'Doit contenir au moins une lettre ou un chiffre' + }); + } else if (!compileCustomFieldPattern(field.pattern).test(normalizeCustomFieldValue(value))) { + errors[key] = + localize(field.patternErrorMessage) ?? + t({ + en: `Must match regular expression: ${field.pattern}`, + es: `Debe coincidir con la expresión regular: ${field.pattern}`, + fr: `Doit correspondre à l'expression régulière : ${field.pattern}` + }); + } + }); + return errors; + }; + + const orderValues = (values: { [K in CustomFieldKey]?: string }) => { + return fields.map((_, index) => values[customFieldKey(index)] ?? ''); + }; + + return { + /** Rejects without a definition, which a form offering the method always has. */ + deriveSubjectId: async (values: { [K in CustomFieldKey]?: string }) => { + if (!definition) { + throw new Error('Cannot derive a subject id without a definition of the custom fields'); + } + return deriveCustomFieldsSubjectId(orderValues(values), { + iterations: definition.iterations, + salt: definition.salt + }); + }, + findErrors, + formFields, + label: definition ? (localize(definition.label) ?? '') : null, + orderValues, + shape + }; +} diff --git a/apps/web/src/hooks/useSubjectIdentificationSettingsQuery.ts b/apps/web/src/hooks/useSubjectIdentificationSettingsQuery.ts new file mode 100644 index 000000000..52664fceb --- /dev/null +++ b/apps/web/src/hooks/useSubjectIdentificationSettingsQuery.ts @@ -0,0 +1,19 @@ +import { $SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { queryOptions, useSuspenseQuery } from '@tanstack/react-query'; +import axios from 'axios'; + +const SUBJECT_IDENTIFICATION_SETTINGS_QUERY_KEY = 'subject-identification-settings'; + +export const subjectIdentificationSettingsQueryOptions = () => { + return queryOptions({ + queryFn: async () => { + const response = await axios.get('/v1/subjects/identification/settings'); + return $SubjectIdentificationSettings.parseAsync(response.data); + }, + queryKey: [SUBJECT_IDENTIFICATION_SETTINGS_QUERY_KEY] + }); +}; + +export function useSubjectIdentificationSettingsQuery() { + return useSuspenseQuery(subjectIdentificationSettingsQueryOptions()); +} diff --git a/apps/web/src/routes/_app/datahub/subjects/index.tsx b/apps/web/src/routes/_app/datahub/subjects/index.tsx index cf8d8b8ac..c2eafab19 100644 --- a/apps/web/src/routes/_app/datahub/subjects/index.tsx +++ b/apps/web/src/routes/_app/datahub/subjects/index.tsx @@ -20,6 +20,7 @@ import { IdentificationForm } from '@/components/IdentificationForm'; import { PageHeader } from '@/components/PageHeader'; import { SearchSubmitGuard } from '@/components/SearchSubmitGuard'; import { SortableHeader } from '@/components/SortableHeader'; +import { subjectIdentificationSettingsQueryOptions } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { subjectRecordSummaryQueryOptions, useSubjectRecordSummaryQuery } from '@/hooks/useSubjectRecordSummaryQuery'; import { subjectsQueryOptions, useSubjectsQuery } from '@/hooks/useSubjectsQuery'; import { useAppStore } from '@/store'; @@ -587,7 +588,8 @@ export const Route = createFileRoute('/_app/datahub/subjects/')({ const { currentGroup } = useAppStore.getState(); await Promise.all([ context.queryClient.ensureQueryData(subjectsQueryOptions({ params: { groupId: currentGroup?.id } })), - context.queryClient.ensureQueryData(subjectRecordSummaryQueryOptions({ params: { groupId: currentGroup?.id } })) + context.queryClient.ensureQueryData(subjectRecordSummaryQueryOptions({ params: { groupId: currentGroup?.id } })), + context.queryClient.ensureQueryData(subjectIdentificationSettingsQueryOptions()) ]); } }); diff --git a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx index 9e7650eee..c26caeb6e 100644 --- a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx +++ b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx @@ -2,6 +2,7 @@ import type { ReactNode } from 'react'; import type { $UpdateGroupData, Group } from '@opendatacapture/schemas/group'; import type { CreateSeriesInstrumentResult, TranslatedInstrumentInfo } from '@opendatacapture/schemas/instrument'; +import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; @@ -13,12 +14,18 @@ import '@/services/i18n'; type DeleteCallbacks = { onSettled: () => void; onSuccess: () => void }; type Loader = (ctx: { - context: { queryClient: { fetchQuery: (options: object) => Promise } }; + context: { + queryClient: { + ensureQueryData: (options: object) => Promise; + fetchQuery: (options: object) => Promise; + }; + }; }) => Promise; const mocks = vi.hoisted(() => ({ changeGroup: vi.fn(), createMutateAsync: vi.fn(), + customFields: null as CustomFieldsDefinition | null, deleteMutate: vi.fn(), /** The group as `GET /v1/groups/:id` returns it; the store's copy dates from sign-in. */ fetchedGroup: undefined as Group | undefined, @@ -44,6 +51,10 @@ vi.mock('@/hooks/useDeleteSeriesInstrumentMutation', () => ({ vi.mock('@/hooks/useSetupStateQuery', () => ({ useSetupStateQuery: () => ({ data: { isDemo: mocks.isDemo } }) })); +vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', async (importOriginal) => ({ + ...(await importOriginal()), + useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: mocks.customFields } }) +})); vi.mock('@/hooks/useUpdateGroupMutation', () => ({ useUpdateGroupMutation: () => ({ mutateAsync: mocks.updateMutateAsync }) })); @@ -196,6 +207,7 @@ const resolveCreate = (result: CreateSeriesInstrumentResult) => mocks.createMuta describe('Route', () => { beforeEach(() => { vi.clearAllMocks(); + mocks.customFields = null; mocks.fetchedGroup = undefined; mocks.instruments = defaultInstruments(); mocks.isDemo = false; @@ -708,6 +720,33 @@ describe('Route', () => { }); }); + describe('default identification method', () => { + const methodOptions = () => { + const select = document.querySelector('select[name="defaultIdentificationMethod"]')!; + return Array.from(select.options, (option) => option.textContent).filter(Boolean); + }; + + it('should not offer custom fields as the default before any are defined', () => { + renderPage(); + expect(methodOptions()).toEqual(['Custom Identifier', 'Personal Information']); + }); + + it("should offer custom fields under the administrator's label once they are defined, and save them as the default", async () => { + mocks.customFields = { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) + }; + mocks.store.currentGroup = makeGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_FIELDS' } }); + renderPage(); + expect(methodOptions()).toEqual(['Custom Identifier', 'Personal Information', 'Animal information']); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(mocks.updateMutateAsync.mock.lastCall?.[0].settings?.defaultIdentificationMethod).toBe('CUSTOM_FIELDS'); + }); + }); + describe('session instrument', () => { const requiring = (sessionInstrumentId: string) => { return makeGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_ID', sessionInstrumentId } }); @@ -784,17 +823,30 @@ describe('Route', () => { }); describe('loader', () => { + const queryClient = () => ({ + ensureQueryData: vi.fn(() => Promise.resolve()), + fetchQuery: vi.fn(() => Promise.resolve()) + }); + + it('should prefetch the subject identification settings, which name the custom-fields method', async () => { + const client = queryClient(); + await loader({ context: { queryClient: client } }); + expect(client.ensureQueryData).toHaveBeenCalledWith( + expect.objectContaining({ queryKey: ['subject-identification-settings'] }) + ); + }); + it('should fetch the current group even when it is cached, since the form saves every setting it is seeded with', async () => { - const fetchQuery = vi.fn(() => Promise.resolve()); - await loader({ context: { queryClient: { fetchQuery } } }); - expect(fetchQuery).toHaveBeenCalledWith(expect.objectContaining({ queryKey: ['group', 'group-1'] })); + const client = queryClient(); + await loader({ context: { queryClient: client } }); + expect(client.fetchQuery).toHaveBeenCalledWith(expect.objectContaining({ queryKey: ['group', 'group-1'] })); }); - it('should fetch nothing when no group is selected', async () => { + it('should fetch no group when none is selected', async () => { mocks.store.currentGroup = null; - const fetchQuery = vi.fn(() => Promise.resolve()); - await loader({ context: { queryClient: { fetchQuery } } }); - expect(fetchQuery).not.toHaveBeenCalled(); + const client = queryClient(); + await loader({ context: { queryClient: client } }); + expect(client.fetchQuery).not.toHaveBeenCalled(); }); }); }); diff --git a/apps/web/src/routes/_app/group/manage.tsx b/apps/web/src/routes/_app/group/manage.tsx index a463472d6..134128ff2 100644 --- a/apps/web/src/routes/_app/group/manage.tsx +++ b/apps/web/src/routes/_app/group/manage.tsx @@ -18,7 +18,6 @@ import { $RegexString, toInstrumentAuthoringLanguage } from '@opendatacapture/sc import type { $UpdateGroupData } from '@opendatacapture/schemas/group'; import type { $CreateSeriesInstrumentData } from '@opendatacapture/schemas/instrument'; import { $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; -import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; import { createFileRoute } from '@tanstack/react-router'; import { EyeIcon, TrashIcon } from 'lucide-react'; import type { Promisable } from 'type-fest'; @@ -33,8 +32,13 @@ import { useDeleteSeriesInstrumentMutation } from '@/hooks/useDeleteSeriesInstru import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { useInstrumentInfoQuery } from '@/hooks/useInstrumentInfoQuery'; import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; +import { + subjectIdentificationSettingsQueryOptions, + useSubjectIdentificationSettingsQuery +} from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useUpdateGroupMutation } from '@/hooks/useUpdateGroupMutation'; import { useAppStore } from '@/store'; +import { getValueForLanguage } from '@/utils/language'; import { buildSeriesAvailability } from '@/utils/series-availability'; /** @@ -85,7 +89,7 @@ const expandSelectedSeriesIds = ({ const NO_SESSION_INSTRUMENT = 'NONE'; type SettingsValues = { - defaultIdentificationMethod?: SubjectIdentificationMethod; + defaultIdentificationMethod?: string; idValidationRegex?: null | string; idValidationRegexErrorMessageEn?: null | string; idValidationRegexErrorMessageFr?: null | string; @@ -96,6 +100,8 @@ type SettingsValues = { }; type ManageGroupFormProps = { + /** The admin's label for the custom fields, or null while none are defined, which leaves the method unavailable. */ + customFieldsLabel: null | string; data: { // The titles of every visible instrument, used to enforce unique new series instrument names. existingTitles: string[]; @@ -562,7 +568,7 @@ const DeleteInstrumentDialog = ({ ); }; -const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => { +const ManageGroupForm = ({ customFieldsLabel, data, onSubmit, readOnly }: ManageGroupFormProps) => { const { existingTitles, groupId, hiddenAccessibleIds, initialSelectedIds, instruments, settingsInitialValues } = data; const { t } = useTranslation(); const [search, setSearch] = useState(''); @@ -599,6 +605,12 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => [instruments] ); + const identificationMethodOptions: { [method: string]: string } = { + CUSTOM_ID: t('common.customIdentifier'), + PERSONAL_INFO: t('common.personalInfo'), + ...(customFieldsLabel === null ? {} : { CUSTOM_FIELDS: customFieldsLabel }) + }; + // Only a form the group will be able to access may be required, so the options follow the selection. // The list holds the latest edition of each form, so a shared title is two forms, told apart by name. const selectedForms = instruments.form.filter((item) => selectedIds.has(item.id)); @@ -753,10 +765,7 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => defaultIdentificationMethod: { kind: 'string', label: t('group.manage.defaultSubjectIdMethod'), - options: { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo') - }, + options: identificationMethodOptions, variant: 'select' }, idValidationRegex: { @@ -836,7 +845,7 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => readOnly={readOnly} validationSchema={z .object({ - defaultIdentificationMethod: $SubjectIdentificationMethod.optional(), + defaultIdentificationMethod: z.enum(Object.keys(identificationMethodOptions)).optional(), idValidationRegex: $RegexString.optional(), idValidationRegexErrorMessageEn: z.string().optional(), idValidationRegexErrorMessageFr: z.string().optional(), @@ -887,7 +896,10 @@ const ManageGroupForm = ({ data, onSubmit, readOnly }: ManageGroupFormProps) => }) ].filter((id) => !deletedIds.has(id)), settings: { - defaultIdentificationMethod: formData.defaultIdentificationMethod, + // The select holds a string, since which methods it offers is known only at runtime. + defaultIdentificationMethod: $SubjectIdentificationMethod + .optional() + .parse(formData.defaultIdentificationMethod), idValidationRegex: formData.idValidationRegex, idValidationRegexErrorMessage: { en: formData.idValidationRegexErrorMessageEn, @@ -916,6 +928,8 @@ const RouteComponent = () => { // seeded with, so seeding it from that copy would undo any change made since. const groupQuery = useGroupQuery(currentGroup?.id); const group = groupQuery.data; + const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); + const customFieldsDefinition = subjectIdentificationSettingsQuery.data.customFields; const availableInstruments = instrumentInfoQuery.data; @@ -1021,6 +1035,9 @@ const RouteComponent = () => { Component={ManageGroupForm} key={currentGroup?.id} props={{ + customFieldsLabel: customFieldsDefinition + ? (getValueForLanguage(customFieldsDefinition.label, resolvedLanguage) ?? '') + : null, data, onSubmit: async (data) => { const updatedGroup = await updateGroupMutation.mutateAsync(data); @@ -1035,11 +1052,12 @@ const RouteComponent = () => { export const Route = createFileRoute('/_app/group/manage')({ component: RouteComponent, - // Fetched even when cached, since the form is seeded once and saves every setting it was seeded with. loader: async ({ context }) => { const { currentGroup } = useAppStore.getState(); - if (currentGroup) { - await context.queryClient.fetchQuery(groupQueryOptions(currentGroup.id)); - } + await Promise.all([ + // Fetched even when cached, since the form is seeded once and saves every setting it was seeded with. + currentGroup ? context.queryClient.fetchQuery(groupQueryOptions(currentGroup.id)) : null, + context.queryClient.ensureQueryData(subjectIdentificationSettingsQueryOptions()) + ]); } }); diff --git a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx index 254aa1fff..44d5c5bc2 100644 --- a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx +++ b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx @@ -12,6 +12,7 @@ import '@/services/i18n'; type StartSessionFormProps = { currentGroup: Group | null; + customFieldsDefinition: unknown; customSubjectIds: string[]; initialValues: { [key: string]: unknown }; onSubmit: (data: $CreateSessionData) => Promise; @@ -70,6 +71,10 @@ vi.mock('@/hooks/useGroupQuery', async (importOriginal) => ({ ...(await importOriginal()), useGroupQuery: (groupId: string | undefined) => ({ data: groupId ? mocks.fetchedGroup : undefined }) })); +vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', async (importOriginal) => ({ + ...(await importOriginal()), + useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: CUSTOM_FIELDS, isCustomFieldsLocked: false } }) +})); vi.mock('@/hooks/useSubjectCustomIdsQuery', async (importOriginal) => ({ ...(await importOriginal()), useSubjectCustomIdsQuery: () => ({ data: ['group-1$CUSTOM-1', 'CUSTOM-2'] }) @@ -82,6 +87,13 @@ vi.mock('@/store', () => ({ const NOW = new Date('2026-01-01T12:00:00Z'); +const CUSTOM_FIELDS = vi.hoisted(() => ({ + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) +})); + const group: Group = { accessibleInstrumentIds: [], createdAt: NOW, @@ -145,6 +157,11 @@ describe('Route', () => { expect(formProps().readOnly).toBe(true); }); + it("should hand the form the instance's custom identifying fields", () => { + render(); + expect(formProps().customFieldsDefinition).toBe(CUSTOM_FIELDS); + }); + it('should suggest the custom ids of the group with their group scope removed', () => { render(); expect(formProps().customSubjectIds).toEqual(['CUSTOM-1', 'CUSTOM-2']); @@ -354,7 +371,16 @@ describe('Route', () => { mocks.store.currentGroup = null; const ensureQueryData = vi.fn(() => Promise.resolve()); await loader({ context: { queryClient: { ensureQueryData } } }); - expect(ensureQueryData).toHaveBeenCalledOnce(); + expect(ensureQueryData).not.toHaveBeenCalledWith(expect.objectContaining({ queryKey: ['group', undefined] })); + expect(ensureQueryData).toHaveBeenCalledTimes(2); + }); + + it('should prefetch the subject identification settings, which the form identifies subjects by', async () => { + const ensureQueryData = vi.fn(() => Promise.resolve()); + await loader({ context: { queryClient: { ensureQueryData } } }); + expect(ensureQueryData).toHaveBeenCalledWith( + expect.objectContaining({ queryKey: ['subject-identification-settings'] }) + ); }); }); }); diff --git a/apps/web/src/routes/_app/session/start-session.tsx b/apps/web/src/routes/_app/session/start-session.tsx index fd0556ff9..0371778e5 100644 --- a/apps/web/src/routes/_app/session/start-session.tsx +++ b/apps/web/src/routes/_app/session/start-session.tsx @@ -15,6 +15,10 @@ import type { StartSessionFormData } from '@/components/StartSessionForm'; import { useCreateSessionMutation } from '@/hooks/useCreateSessionMutation'; import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { subjectCustomIdsQueryOptions, useSubjectCustomIdsQuery } from '@/hooks/useSubjectCustomIdsQuery'; +import { + subjectIdentificationSettingsQueryOptions, + useSubjectIdentificationSettingsQuery +} from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useAppStore } from '@/store'; type PendingSession = { @@ -42,6 +46,7 @@ const RouteComponent = () => { const subjectCustomIdsQuery = useSubjectCustomIdsQuery({ params: { groupId: currentGroup?.id } }); // The store holds the group as it was at sign-in, so a session instrument chosen since is read fresh. const groupQuery = useGroupQuery(currentGroup?.id); + const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); const customSubjectIds = subjectCustomIdsQuery.data.map(removeSubjectIdScope); @@ -74,6 +79,7 @@ const RouteComponent = () => {
diff --git a/docs/en/4-concepts/4.2-hash-based-identification.md b/docs/en/4-concepts/4.2-hash-based-identification.md index 07b3ef2b8..c26e96a41 100644 --- a/docs/en/4-concepts/4.2-hash-based-identification.md +++ b/docs/en/4-concepts/4.2-hash-based-identification.md @@ -57,3 +57,26 @@ No secret is added to the input, so anyone who knows a person's name, date of bi This output is used as the identifier for René Tremblay. Her first and last name are not entered into the database, and we store her date of birth and sex, alongside her identifier. + +## Custom Fields + +An administrator can define an instance's own identifying fields instead, for example an animal's ear tag and its cage. Staff then choose the method under the label the administrator gave it, and Start Session and the Data Hub's subject lookup ask for those fields. Every field is required. Date of birth and sex are optional, as they are for a custom identifier. + +The administrator defines the fields once, under **Admin Panel** > **Instance** > **Settings**, on the **Subject Identification** tab. Each field has a label, optional help text, a pattern the value must match and an optional message shown when it does not. The values typed are never sent to the server and never stored; your browser derives the identifier from them, and a subject who returns is recognized when the same values are typed again. + +### How the identifier is derived + +Your browser standardizes each value: + +1. Letters are converted to uppercase. +2. Accents are separated from their letters, and the full-width digits and letters some keyboards produce become ordinary ones. +3. A few Latin letters that have no accent to remove are spelled out: Œ as OE, Æ as AE, Ø as O, Ł as L, Đ and Ð as D, and Þ as TH. +4. Everything that is not a letter or a digit is removed: spaces, hyphens, apostrophes and all other punctuation. + +So "ab-12 34" and "AB1234" are the same value, as are "Sørensen" and "SORENSEN". Letters in other scripts are kept as they are, so "李" and "里" stay two different values. A value that has no letter or digit left is refused, and the pattern is tested against the standardized value, which holds only letters and digits, with Latin letters in uppercase. + +The standardized values are then combined, in the order the fields are defined, and passed through PBKDF2 with SHA-256, 600,000 rounds and a random key, called a salt, that the instance generates when the fields are first defined. The identifier is `cf_` followed by the 64 hexadecimal characters of the result. Because of the salt, someone holding only an export of the data cannot recover a short identifier by trying every possible value, and the same values give different identifiers on two instances. + +### Once a subject has been identified + +The standardization, the order of the fields, the salt and the number of rounds are part of every identifier, and the values typed are not stored, so none of them can change once any subject has been identified with the fields. From then on the number and order of the fields are locked. The labels, help text, patterns and messages can still be corrected, but a label should not be repurposed: renaming "Animal ID" to "Cage number" would have staff type something else, and every returning subject would get a new identifier. diff --git a/packages/schemas/src/subject/subject.ts b/packages/schemas/src/subject/subject.ts index 3a292b851..c59a762fe 100644 --- a/packages/schemas/src/subject/subject.ts +++ b/packages/schemas/src/subject/subject.ts @@ -3,7 +3,7 @@ import { z } from 'zod/v4'; import { $BaseModel, $DateLike } from '../core/core.js'; export type SubjectIdentificationMethod = z.infer; -export const $SubjectIdentificationMethod = z.enum(['CUSTOM_ID', 'PERSONAL_INFO']); +export const $SubjectIdentificationMethod = z.enum(['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS']); export type Sex = z.infer; export const $Sex = z.enum(['MALE', 'FEMALE']); diff --git a/packages/subject-utils/AGENTS.md b/packages/subject-utils/AGENTS.md index 532b77c5d..6b71b2d1a 100644 --- a/packages/subject-utils/AGENTS.md +++ b/packages/subject-utils/AGENTS.md @@ -2,7 +2,7 @@ Derives and formats clinical subject identifiers. Nine exports: `generateSubjectHash`, `encodeScopedSubjectId`, `isSubjectWithPersonalInfo`, `inferSubjectIdentificationMethod`, -`toStoredSubjectId`, `isCustomFieldsSubjectId`, `normalizeCustomFieldValue`, +`toStoredSubjectId`, `CUSTOM_FIELDS_SUBJECT_ID_PREFIX`, `normalizeCustomFieldValue`, `deriveCustomFieldsSubjectId`, and `removeSubjectIdScope` (re-exported from `@opendatacapture/runtime-internal`). Source-only — `exports` is `"./src/index.ts"`, no build step. Used by `apps/web`, `apps/api` and `packages/react-core`. diff --git a/packages/subject-utils/src/__tests__/index.test.ts b/packages/subject-utils/src/__tests__/index.test.ts index 1dc3042ae..b2e7bd1b5 100644 --- a/packages/subject-utils/src/__tests__/index.test.ts +++ b/packages/subject-utils/src/__tests__/index.test.ts @@ -6,7 +6,6 @@ import { encodeScopedSubjectId, generateSubjectHash, inferSubjectIdentificationMethod, - isCustomFieldsSubjectId, isSubjectWithPersonalInfo, normalizeCustomFieldValue, removeSubjectIdScope, @@ -194,6 +193,15 @@ describe('inferSubjectIdentificationMethod', () => { it('should read any other value as a custom id', () => { expect(inferSubjectIdentificationMethod('ex_111')).toBe('CUSTOM_ID'); }); + it('should read cf_ followed by 64 lowercase hex characters as derived from custom fields', () => { + expect(inferSubjectIdentificationMethod(customFieldsSubjectId)).toBe('CUSTOM_FIELDS'); + }); + it('should read cf_ followed by uppercase hex as a custom id, since derivation never writes it', () => { + expect(inferSubjectIdentificationMethod(`cf_${nameHash.toUpperCase()}`)).toBe('CUSTOM_ID'); + }); + it('should read cf_ followed by a digest of the wrong length as a custom id', () => { + expect(inferSubjectIdentificationMethod(customFieldsSubjectId.slice(0, -1))).toBe('CUSTOM_ID'); + }); }); describe('toStoredSubjectId', () => { @@ -216,21 +224,6 @@ describe('toStoredSubjectId', () => { }); }); -describe('isCustomFieldsSubjectId', () => { - it('should accept cf_ followed by 64 lowercase hex characters', () => { - expect(isCustomFieldsSubjectId(customFieldsSubjectId)).toBe(true); - }); - it('should reject uppercase hex, which derivation never writes', () => { - expect(isCustomFieldsSubjectId(`cf_${nameHash.toUpperCase()}`)).toBe(false); - }); - it('should reject a digest of the wrong length', () => { - expect(isCustomFieldsSubjectId(customFieldsSubjectId.slice(0, -1))).toBe(false); - }); - it('should reject a bare digest, which is a name hash', () => { - expect(isCustomFieldsSubjectId(nameHash)).toBe(false); - }); -}); - describe('normalizeCustomFieldValue', () => { it.each([ ['Jané', 'JANE'], @@ -306,9 +299,9 @@ describe('deriveCustomFieldsSubjectId', () => { 'cf_ee997483bb6ef14ebb034cb15635cf14b8f5a7a5a0487ea6ccd971fc3d281f8f' ]); }); - it('should derive an id isCustomFieldsSubjectId accepts', async () => { + it('should derive an id read back as derived from custom fields', async () => { const id = await deriveCustomFieldsSubjectId(['AB12'], { iterations: 1, salt }); - expect(isCustomFieldsSubjectId(id)).toBe(true); + expect(inferSubjectIdentificationMethod(id)).toBe('CUSTOM_FIELDS'); }); it('should refuse a value that normalizes to nothing, rather than hash an empty field', async () => { await expect(deriveCustomFieldsSubjectId(['AB12', '--'], { iterations: 1000, salt })).rejects.toThrow( diff --git a/packages/subject-utils/src/index.ts b/packages/subject-utils/src/index.ts index e0009fbf0..f08235af6 100644 --- a/packages/subject-utils/src/index.ts +++ b/packages/subject-utils/src/index.ts @@ -92,20 +92,17 @@ export function encodeScopedSubjectId(id: string, options: { groupName: string } } export function inferSubjectIdentificationMethod(subjectId: string): SubjectIdentificationMethod { - return PERSONAL_INFO_SUBJECT_ID_PATTERN.test(subjectId) ? 'PERSONAL_INFO' : 'CUSTOM_ID'; -} - -export function isCustomFieldsSubjectId(subjectId: string): boolean { - return CUSTOM_FIELDS_SUBJECT_ID_PATTERN.test(subjectId); + if (CUSTOM_FIELDS_SUBJECT_ID_PATTERN.test(subjectId)) { + return 'CUSTOM_FIELDS'; + } else if (PERSONAL_INFO_SUBJECT_ID_PATTERN.test(subjectId)) { + return 'PERSONAL_INFO'; + } + return 'CUSTOM_ID'; } export function toStoredSubjectId(enteredId: string, options: { groupName: string }): string { // Only a custom id belongs to a group; a name hash or a custom-fields id names the same subject in every group. - if ( - enteredId.includes('$') || - isCustomFieldsSubjectId(enteredId) || - inferSubjectIdentificationMethod(enteredId) !== 'CUSTOM_ID' - ) { + if (enteredId.includes('$') || inferSubjectIdentificationMethod(enteredId) !== 'CUSTOM_ID') { return enteredId; } return encodeScopedSubjectId(enteredId, options); diff --git a/testing/src/pages/_app/session/start-session.page.ts b/testing/src/pages/_app/session/start-session.page.ts index a772d0372..f172a924c 100644 --- a/testing/src/pages/_app/session/start-session.page.ts +++ b/testing/src/pages/_app/session/start-session.page.ts @@ -37,12 +37,23 @@ export class StartSessionPage extends AppPage { // The end session nav item opens a dialog rather than navigating, so it carries no route. } + /** One of the fields an administrator defined for identifying subjects, in the order defined. */ + customField(index: number): Locator { + return this.sessionForm.locator(`[name="customField${index}"]`); + } + /** Clicks outside the identifier combobox, which closes its popup and commits what was typed. */ async dismissSubjectIdOptions() { // eslint-disable-next-line playwright/prefer-locator -- pageHeader is a Locator; the rule takes any name starting with "page" for a Page await this.pageHeader.click(); } + async fillCustomFields(values: string[]) { + for (const [index, value] of values.entries()) { + await this.customField(index).fill(value); + } + } + async fillCustomIdentifier(customIdentifier: string, sex: string) { await this.typeSubjectId(customIdentifier); await this.fillSessionDetails(sex); diff --git a/testing/src/specs/custom-fields.spec.ts b/testing/src/specs/custom-fields.spec.ts new file mode 100644 index 000000000..52f54b49a --- /dev/null +++ b/testing/src/specs/custom-fields.spec.ts @@ -0,0 +1,81 @@ +import { StartSessionPage } from '../pages/_app/session/start-session.page'; +import { expect, test } from '../support/fixtures'; + +/** + * The definition is one instance-wide document, and it locks for good the first time any subject is + * identified with it, so every scenario using it lives in this one serial file. Its first step keeps + * the number of fields the same on every run, which is what a locked definition still accepts. + */ +const DEFINITION = { + fields: [ + { + label: { en: 'Animal ID' }, + pattern: '[A-Z]{2}[0-9]+', + patternErrorMessage: { en: 'Two letters, then digits' } + }, + { label: { en: 'Cage' }, pattern: '[0-9]+' } + ], + label: { en: 'Animal information' } +}; + +test.describe.configure({ mode: 'serial' }); + +test.describe('custom identifying fields', () => { + let animalId: string; + + test.beforeAll(() => { + animalId = `ab${Date.now()}`; + }); + + test('should define the fields', async ({ api }) => { + const settings = await api.updateSubjectIdentificationSettings({ customFields: DEFINITION }); + expect(settings.customFields).toMatchObject(DEFINITION); + }); + + test('should start a session for a subject identified by the fields, sending no name and no typed value', async ({ + getPageModel, + page + }) => { + const startSessionPage = await getPageModel('/session/start-session'); + await startSessionPage.selectIdentificationMethod('CUSTOM_FIELDS'); + await startSessionPage.fillCustomFields(['a', '7']); + await startSessionPage.submitForm(); + await expect(startSessionPage.subjectIdErrors).toHaveCount(0); + await expect(startSessionPage.errorMessages).toHaveText(['Two letters, then digits']); + + await startSessionPage.fillCustomFields([animalId, '7']); + await startSessionPage.fillSubjectDetails('Female'); + const sessionCreated = page.waitForRequest( + (request) => request.url().endsWith('/v1/sessions') && request.method() === 'POST' + ); + await startSessionPage.submitForm(); + const body = (await sessionCreated).postDataJSON() as { subjectData: { [key: string]: unknown } }; + expect(body.subjectData.id).toMatch(/^cf_[0-9a-f]{64}$/); + expect(body.subjectData).not.toHaveProperty('firstName'); + expect(JSON.stringify(body)).not.toContain(animalId.slice(2)); + await expect(startSessionPage.successMessage).toBeVisible(); + }); + + // Letter case and punctuation are normalized away before hashing, so they name the same subject. + test('should recognize a returning subject from the same values typed differently, filling in and locking their details', async ({ + getPageModel + }) => { + const startSessionPage: StartSessionPage = await getPageModel('/session/start-session'); + await startSessionPage.selectIdentificationMethod('CUSTOM_FIELDS'); + await startSessionPage.fillCustomFields([`${animalId.slice(0, 2).toUpperCase()}-${animalId.slice(2)}`, ' 7 ']); + await expect(startSessionPage.dateOfBirthField).toHaveValue('1990-01-01'); + await expect(startSessionPage.dateOfBirthField).toBeDisabled(); + await expect(startSessionPage.sexTrigger).toBeDisabled(); + }); + + test('should find the subject from the data hub by the same fields', async ({ getPageModel, page }) => { + await getPageModel('/datahub/subjects'); + await page.getByTestId('subject-lookup-search-button').click(); + const identificationForm = page.getByTestId('identification-form'); + await identificationForm.locator('[name="subjectIdentificationMethod"]').selectOption('CUSTOM_FIELDS'); + await identificationForm.locator('[name="customField0"]').fill(animalId); + await identificationForm.locator('[name="customField1"]').fill('7'); + await identificationForm.getByRole('button', { name: 'Submit' }).click(); + await expect(page).toHaveURL(/\/datahub\/subjects\/cf_[0-9a-f]{64}\/table$/); + }); +}); diff --git a/testing/src/specs/datahub.spec.ts b/testing/src/specs/datahub.spec.ts index 94a3869f1..5d84b547a 100644 --- a/testing/src/specs/datahub.spec.ts +++ b/testing/src/specs/datahub.spec.ts @@ -40,7 +40,7 @@ test.describe('data hub', () => { await page.getByTestId('subject-lookup-search-button').click(); const identificationForm = page.getByTestId('identification-form'); - await identificationForm.locator('[name="identificationMethod"]').selectOption('CUSTOM_ID'); + await identificationForm.locator('[name="subjectIdentificationMethod"]').selectOption('CUSTOM_ID'); await identificationForm.locator('[name="id"]').fill(customIdentifier); await identificationForm.getByRole('button', { name: 'Submit' }).click(); diff --git a/testing/src/support/api-client.ts b/testing/src/support/api-client.ts index 99bf3197e..eda603cff 100644 --- a/testing/src/support/api-client.ts +++ b/testing/src/support/api-client.ts @@ -14,6 +14,10 @@ import { MAIL_CLIENT_TIMEOUT } from '@opendatacapture/schemas/mail'; import type { $SendAssignmentEmailData, EmailDeliveryResult } from '@opendatacapture/schemas/mail'; import type { $CreateSessionData, Session, SessionType } from '@opendatacapture/schemas/session'; import type { $CreateSubjectData } from '@opendatacapture/schemas/subject'; +import type { + $UpdateSubjectIdentificationSettingsData, + SubjectIdentificationSettings +} from '@opendatacapture/schemas/subject-identification'; import type { $CreateUserData, $UpdateUserPermissionsData, User } from '@opendatacapture/schemas/user'; import type { APIRequestContext } from '@playwright/test'; @@ -330,6 +334,17 @@ export class ApiClient { ); } + /** Replaces the instance's subject identification settings as admin. */ + async updateSubjectIdentificationSettings( + data: $UpdateSubjectIdentificationSettingsData + ): Promise { + return this.expectJson( + this.request.put(`${API}/subjects/identification/settings`, { data, headers: this.authHeaders }), + 200, + 'update subject identification settings' + ); + } + /** * Bulk-creates one record per entry, and with them the subjects and sessions they name. Returns * the records the api reports created, which the upload contract scopes to this request alone. From 3d3877008795ef70f469464ad852f1097f2316f0 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 11:45:03 -0500 Subject: [PATCH 17/19] feat(web): define the fields that identify subjects on the settings page Adds a Subject Identification tab to /admin/settings where an admin defines the CUSTOM_FIELDS method: its label in each active language and an ordered list of one to ten fields, each with a label, optional help text, a pattern and an optional error message. A test box beside each pattern shows what a typed value normalizes to and whether the pattern, compiled as the forms compile it, accepts it. The tab saves one draft with one button. The first definition asks for confirmation, since its field list is fixed once a subject has been identified with it. Once locked, the fields can no longer be added, removed or reordered and the definition cannot be removed; their text and patterns stay editable. A save the lock refuses reloads the saved definition. Co-Authored-By: Claude Opus 5.5 --- .../SubjectIdentificationTab.tsx | 10 + .../__tests__/ApplicationSettings.test.tsx | 3 +- .../SubjectIdentificationTab.test.tsx | 45 +++ .../__tests__/tabs.test.ts | 14 +- .../components/ApplicationSettings/tabs.ts | 9 + .../CustomFieldEditor.tsx | 125 ++++++++ .../CustomFieldTestBox.tsx | 114 +++++++ .../CustomFieldsEditor.tsx | 302 ++++++++++++++++++ .../LocalizedTextInputs.tsx | 67 ++++ .../SubjectIdentificationSettingsForm.tsx | 166 ++++++++++ .../__tests__/CustomFieldEditor.test.tsx | 95 ++++++ .../__tests__/CustomFieldTestBox.test.tsx | 61 ++++ .../__tests__/CustomFieldsEditor.test.tsx | 180 +++++++++++ .../__tests__/LocalizedTextInputs.test.tsx | 52 +++ ...SubjectIdentificationSettingsForm.test.tsx | 198 ++++++++++++ .../index.ts | 1 + ...jectIdentificationSettingsMutation.test.ts | 55 ++++ ...teSubjectIdentificationSettingsMutation.ts | 27 ++ .../subject-identification-draft.test.ts | 122 +++++++ .../src/utils/subject-identification-draft.ts | 83 +++++ 20 files changed, 1727 insertions(+), 2 deletions(-) create mode 100644 apps/web/src/components/ApplicationSettings/SubjectIdentificationTab.tsx create mode 100644 apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldEditor.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldTestBox.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/LocalizedTextInputs.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldEditor.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldTestBox.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/LocalizedTextInputs.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/index.ts create mode 100644 apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts create mode 100644 apps/web/src/hooks/useUpdateSubjectIdentificationSettingsMutation.ts create mode 100644 apps/web/src/utils/__tests__/subject-identification-draft.test.ts create mode 100644 apps/web/src/utils/subject-identification-draft.ts diff --git a/apps/web/src/components/ApplicationSettings/SubjectIdentificationTab.tsx b/apps/web/src/components/ApplicationSettings/SubjectIdentificationTab.tsx new file mode 100644 index 000000000..997bd09cb --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/SubjectIdentificationTab.tsx @@ -0,0 +1,10 @@ +import { SubjectIdentificationSettingsForm } from '@/components/SubjectIdentificationSettingsForm'; +import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; +import { useSubjectIdentificationSettingsQuery } from '@/hooks/useSubjectIdentificationSettingsQuery'; + +export const SubjectIdentificationTab = () => { + const { data: settings } = useSubjectIdentificationSettingsQuery(); + const { data: setupState } = useSetupStateQuery(); + + return ; +}; diff --git a/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx b/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx index 3018b8f47..7d6dd737e 100644 --- a/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx +++ b/apps/web/src/components/ApplicationSettings/__tests__/ApplicationSettings.test.tsx @@ -39,6 +39,7 @@ vi.mock('../InterfaceTab', () => ({ ) })); vi.mock('../MailTab', () => ({ MailTab: mocks.MailTab })); +vi.mock('../SubjectIdentificationTab', () => ({ SubjectIdentificationTab: () => null })); const renderSettings = ({ onTabChange = vi.fn(), @@ -70,7 +71,7 @@ describe('ApplicationSettings', () => { it('should list the tabs by their translated label, so they read alphabetically in every language', () => { i18n.changeLanguage('fr'); renderSettings(); - expect(tabLabels()).toStrictEqual(['Courriel', 'Fonctionnalités', 'Interface']); + expect(tabLabels()).toStrictEqual(['Courriel', 'Fonctionnalités', 'Identification des sujets', 'Interface']); }); // In French the first tab by label is not the first written, so this tells the two orders apart. diff --git a/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx b/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx new file mode 100644 index 000000000..575d7a8c1 --- /dev/null +++ b/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx @@ -0,0 +1,45 @@ +import type { ComponentProps } from 'react'; + +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { cleanup, render } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import type { SubjectIdentificationSettingsForm } from '@/components/SubjectIdentificationSettingsForm'; + +import { SubjectIdentificationTab } from '../SubjectIdentificationTab'; + +const SETTINGS: SubjectIdentificationSettings = { + customFields: { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 600_000, + label: { en: 'Animal information' }, + salt: 'ab'.repeat(32) + }, + isCustomFieldsLocked: true +}; + +const mocks = vi.hoisted(() => ({ + SubjectIdentificationSettingsForm: vi.fn((_: ComponentProps) => null) +})); + +vi.mock('@/components/SubjectIdentificationSettingsForm', () => ({ + SubjectIdentificationSettingsForm: mocks.SubjectIdentificationSettingsForm +})); +vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', () => ({ + useSubjectIdentificationSettingsQuery: () => ({ data: SETTINGS }) +})); +vi.mock('@/hooks/useSetupStateQuery', () => ({ + useSetupStateQuery: () => ({ data: { activeLanguages: ['en', 'fr'] } }) +})); + +describe('SubjectIdentificationTab', () => { + afterEach(cleanup); + + it('should hand the stored settings and the active languages to the settings form', () => { + render(); + expect(mocks.SubjectIdentificationSettingsForm.mock.lastCall?.[0]).toEqual({ + activeLanguages: ['en', 'fr'], + settings: SETTINGS + }); + }); +}); diff --git a/apps/web/src/components/ApplicationSettings/__tests__/tabs.test.ts b/apps/web/src/components/ApplicationSettings/__tests__/tabs.test.ts index 9e7d6119b..024c39e74 100644 --- a/apps/web/src/components/ApplicationSettings/__tests__/tabs.test.ts +++ b/apps/web/src/components/ApplicationSettings/__tests__/tabs.test.ts @@ -4,13 +4,18 @@ import { describe, expect, it, vi } from 'vitest'; import { $ApplicationSettingsSearch, SETTINGS_TABS } from '../tabs'; const mocks = vi.hoisted(() => ({ - mailSettingsQueryOptions: vi.fn(() => ({ queryKey: ['mail-settings'] })) + mailSettingsQueryOptions: vi.fn(() => ({ queryKey: ['mail-settings'] })), + subjectIdentificationSettingsQueryOptions: vi.fn(() => ({ queryKey: ['subject-identification-settings'] })) })); vi.mock('@/hooks/useMailSettingsQuery', () => ({ mailSettingsQueryOptions: mocks.mailSettingsQueryOptions })); +vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', () => ({ + subjectIdentificationSettingsQueryOptions: mocks.subjectIdentificationSettingsQueryOptions +})); vi.mock('../FeaturesTab', () => ({ FeaturesTab: () => null })); vi.mock('../InterfaceTab', () => ({ InterfaceTab: () => null })); vi.mock('../MailTab', () => ({ MailTab: () => null })); +vi.mock('../SubjectIdentificationTab', () => ({ SubjectIdentificationTab: () => null })); describe('$ApplicationSettingsSearch', () => { it('should leave the tab unset for a bare address, so the router does not rewrite it to add one', () => { @@ -33,4 +38,11 @@ describe('SETTINGS_TABS', () => { await SETTINGS_TABS.find(({ value }) => value === 'mail')?.prefetch?.(queryClient); expect(ensureQueryData).toHaveBeenCalledWith({ queryKey: ['mail-settings'] }); }); + + it('should prefetch the subject identification settings for their tab, so it renders without a waterfall', async () => { + const queryClient = new QueryClient(); + const ensureQueryData = vi.spyOn(queryClient, 'ensureQueryData').mockResolvedValue(undefined); + await SETTINGS_TABS.find(({ value }) => value === 'subject-identification')?.prefetch?.(queryClient); + expect(ensureQueryData).toHaveBeenCalledWith({ queryKey: ['subject-identification-settings'] }); + }); }); diff --git a/apps/web/src/components/ApplicationSettings/tabs.ts b/apps/web/src/components/ApplicationSettings/tabs.ts index 0cad33f7e..1404f1ebb 100644 --- a/apps/web/src/components/ApplicationSettings/tabs.ts +++ b/apps/web/src/components/ApplicationSettings/tabs.ts @@ -1,10 +1,12 @@ import { z } from 'zod/v4'; import { mailSettingsQueryOptions } from '@/hooks/useMailSettingsQuery'; +import { subjectIdentificationSettingsQueryOptions } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { FeaturesTab } from './FeaturesTab'; import { InterfaceTab } from './InterfaceTab'; import { MailTab } from './MailTab'; +import { SubjectIdentificationTab } from './SubjectIdentificationTab'; import type { SettingsTab } from './types'; @@ -31,6 +33,13 @@ export const SETTINGS_TABS = defineSettingsTabs([ prefetch: (queryClient) => queryClient.ensureQueryData(mailSettingsQueryOptions()), saves: 'explicit', value: 'mail' + }, + { + Content: SubjectIdentificationTab, + label: { en: 'Subject Identification', es: 'Identificación de sujetos', fr: 'Identification des sujets' }, + prefetch: (queryClient) => queryClient.ensureQueryData(subjectIdentificationSettingsQueryOptions()), + saves: 'explicit', + value: 'subject-identification' } ]); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldEditor.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldEditor.tsx new file mode 100644 index 000000000..9ebfaf658 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldEditor.tsx @@ -0,0 +1,125 @@ +import type React from 'react'; + +import { Input } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { Language } from '@opendatacapture/schemas/core'; +import { compileCustomFieldPattern } from '@opendatacapture/schemas/subject-identification'; + +import { FormField } from '@/components/FormField'; +import { findCustomFieldIssues } from '@/utils/subject-identification-draft'; +import type { CustomFieldDraft } from '@/utils/subject-identification-draft'; + +import { CustomFieldTestBox } from './CustomFieldTestBox'; +import { LocalizedTextInputs } from './LocalizedTextInputs'; + +export type CustomFieldEditorProps = { + activeLanguages: readonly Language[]; + /** Shown beside the field's heading: the controls that move or remove it, while the list may change. */ + listControls?: React.ReactNode; + onChange: (field: CustomFieldDraft) => void; + /** The field's position, from 0, which its test ids carry, e.g. `custom-field-0-pattern`. */ + position: number; + /** Shows a missing label or pattern as an error. A pattern that does not compile is shown regardless. */ + showErrors: boolean; + value: CustomFieldDraft; +}; + +export const CustomFieldEditor = ({ + activeLanguages, + listControls, + onChange, + position, + showErrors, + value +}: CustomFieldEditorProps) => { + const { t } = useTranslation(); + const issues = findCustomFieldIssues(value); + const idPrefix = `custom-field-${position}`; + + const findPatternError = () => { + if (!issues.pattern) { + return undefined; + } else if (value.pattern !== '') { + return t({ + en: 'This is not a valid regular expression.', + es: 'Esta no es una expresión regular válida.', + fr: "Ce n'est pas une expression régulière valide." + }); + } + return showErrors + ? t({ en: 'Enter a pattern.', es: 'Introduzca un patrón.', fr: 'Saisissez un motif.' }) + : undefined; + }; + + return ( +
+
+

+ {t({ en: `Field ${position + 1}`, es: `Campo ${position + 1}`, fr: `Champ ${position + 1}` })} +

+ {listControls} +
+ onChange({ ...value, label })} + /> + onChange({ ...value, description })} + /> + + onChange({ ...value, pattern: event.target.value })} + /> + + onChange({ ...value, patternErrorMessage })} + /> + +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldTestBox.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldTestBox.tsx new file mode 100644 index 000000000..dc690ecf7 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldTestBox.tsx @@ -0,0 +1,114 @@ +import { useState } from 'react'; + +import { Input, Label } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import { cn } from '@douglasneuroinformatics/libui/utils'; +import { CUSTOM_FIELD_MAX_VALUE_LENGTH } from '@opendatacapture/schemas/subject-identification'; +import { normalizeCustomFieldValue } from '@opendatacapture/subject-utils'; + +type SampleVerdict = 'accepted' | 'no-pattern' | 'normalizes-to-nothing' | 'rejected' | 'too-long'; + +// In the order the forms refuse a value: its length as typed, then what is left once normalized, +// then the pattern, which tests the normalized value. +const judgeSample = (sample: string, normalized: string, compiledPattern: null | RegExp): SampleVerdict => { + if (sample.length > CUSTOM_FIELD_MAX_VALUE_LENGTH) { + return 'too-long'; + } else if (normalized === '') { + return 'normalizes-to-nothing'; + } else if (compiledPattern === null) { + return 'no-pattern'; + } + return compiledPattern.test(normalized) ? 'accepted' : 'rejected'; +}; + +export type CustomFieldTestBoxProps = { + /** Null while the field's pattern is missing or does not compile. */ + compiledPattern: null | RegExp; + /** The box's test ids are this followed by `-input`, `-result` and `-normalized`. */ + idPrefix: string; +}; + +/** + * Shows what a typed value becomes and whether the pattern accepts it. Patterns see only uppercase + * letters and digits, which is easy to forget without seeing a value go through. + */ +export const CustomFieldTestBox = ({ compiledPattern, idPrefix }: CustomFieldTestBoxProps) => { + const { t } = useTranslation(); + const [sample, setSample] = useState(''); + + const normalized = normalizeCustomFieldValue(sample); + const verdict = judgeSample(sample, normalized, compiledPattern); + const verdictMessages: { [K in SampleVerdict]: string } = { + accepted: t({ + en: 'Accepted: the pattern matches this value.', + es: 'Aceptado: el patrón coincide con este valor.', + fr: 'Accepté : le motif correspond à cette valeur.' + }), + 'no-pattern': t({ + en: 'Enter a valid pattern to test this value against it.', + es: 'Introduzca un patrón válido para probar este valor.', + fr: 'Saisissez un motif valide pour tester cette valeur.' + }), + 'normalizes-to-nothing': t({ + en: 'Refused: this value has no letters or digits, so nothing is left once it is normalized.', + es: 'Rechazado: este valor no tiene letras ni dígitos, por lo que no queda nada una vez normalizado.', + fr: 'Refusé : cette valeur ne contient ni lettre ni chiffre, il ne reste donc rien une fois normalisée.' + }), + rejected: t({ + en: 'Rejected: the pattern does not match this value.', + es: 'Rechazado: el patrón no coincide con este valor.', + fr: 'Rejeté : le motif ne correspond pas à cette valeur.' + }), + 'too-long': t( + { + en: 'Refused: a value is at most {} characters long.', + es: 'Rechazado: un valor tiene como máximo {} caracteres.', + fr: 'Refusé : une valeur compte au plus {} caractères.' + }, + { args: [CUSTOM_FIELD_MAX_VALUE_LENGTH] } + ) + }; + + return ( +
+ +

+ {t({ + en: 'Type a value as staff would. It is uppercased and stripped of everything but letters and digits, as it will be when a subject is identified, and then tested against the pattern.', + es: 'Escriba un valor como lo haría el personal. Se pasa a mayúsculas y se le quita todo lo que no sean letras y dígitos, como ocurrirá al identificar a un sujeto, y luego se prueba con el patrón.', + fr: "Saisissez une valeur comme le ferait le personnel. Elle est mise en majuscules et débarrassée de tout ce qui n'est pas une lettre ou un chiffre, comme lors de l'identification d'un sujet, puis testée avec le motif." + })} +

+ setSample(event.target.value)} + /> + {sample !== '' && ( +
+
+ + {t({ en: 'Normalized:', es: 'Normalizado:', fr: 'Normalisée :' })} + + + {normalized} + +
+

+ {verdictMessages[verdict]} +

+
+ )} +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx new file mode 100644 index 000000000..ec6f63ace --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx @@ -0,0 +1,302 @@ +import { Button, Heading } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { Language } from '@opendatacapture/schemas/core'; +import { CUSTOM_FIELDS_MAX_FIELD_COUNT } from '@opendatacapture/schemas/subject-identification'; +import { ChevronDownIcon, ChevronUpIcon, LockIcon, LockOpenIcon, PlusIcon, Trash2Icon } from 'lucide-react'; + +import { SectionCard } from '@/components/SectionCard'; +import { + createCustomFieldDraft, + createCustomFieldsDraft, + isCustomFieldsLabelMissing +} from '@/utils/subject-identification-draft'; +import type { CustomFieldDraft, CustomFieldsDraft } from '@/utils/subject-identification-draft'; + +import { CustomFieldEditor } from './CustomFieldEditor'; +import { LocalizedTextInputs } from './LocalizedTextInputs'; + +type LockStatusProps = { + isLocked: boolean; +}; + +const LockStatus = ({ isLocked }: LockStatusProps) => { + const { t } = useTranslation(); + return ( +
+ {isLocked ? ( + + ) : ( + + )} +
+

+ {isLocked + ? t({ en: 'Locked', es: 'Bloqueado', fr: 'Verrouillé' }) + : t({ en: 'Not Locked', es: 'No bloqueado', fr: 'Non verrouillé' })} +

+

+ {isLocked + ? t({ + en: 'Subjects have been identified with these fields, so their number and order can no longer change and the definition cannot be removed. Labels, help text, patterns and error messages can still be edited.', + es: 'Se han identificado sujetos con estos campos, por lo que su número y su orden ya no pueden cambiar y la definición no se puede eliminar. Las etiquetas, los textos de ayuda, los patrones y los mensajes de error siguen siendo editables.', + fr: "Des sujets ont été identifiés avec ces champs : leur nombre et leur ordre ne peuvent plus changer et la définition ne peut plus être supprimée. Les étiquettes, les textes d'aide, les motifs et les messages d'erreur restent modifiables." + }) + : t({ + en: 'No subject has been identified with these fields yet, so they can still be added, removed and reordered. Their number and order are fixed once one is.', + es: 'Todavía no se ha identificado ningún sujeto con estos campos, por lo que aún se pueden agregar, eliminar y reordenar. Su número y su orden quedan fijos en cuanto se identifique uno.', + fr: "Aucun sujet n'a encore été identifié avec ces champs : ils peuvent encore être ajoutés, supprimés et réordonnés. Leur nombre et leur ordre sont figés dès qu'un sujet l'est." + })} +

+
+
+ ); +}; + +type FieldListControlsProps = { + fieldCount: number; + onMoveDown: () => void; + onMoveUp: () => void; + onRemove: () => void; + position: number; +}; + +const FieldListControls = ({ fieldCount, onMoveDown, onMoveUp, onRemove, position }: FieldListControlsProps) => { + const { t } = useTranslation(); + return ( +
+ + + +
+ ); +}; + +type DefinitionEditorProps = { + activeLanguages: readonly Language[]; + isLocked: boolean; + onChange: (value: CustomFieldsDraft | null) => void; + showErrors: boolean; + value: CustomFieldsDraft; +}; + +const DefinitionEditor = ({ activeLanguages, isLocked, onChange, showErrors, value }: DefinitionEditorProps) => { + const { t } = useTranslation(); + const { fields } = value; + const updateFields = (next: CustomFieldDraft[]) => onChange({ ...value, fields: next }); + // Swaps the field at `position` with the one before it. + const raiseField = (position: number) => { + updateFields([ + ...fields.slice(0, position - 1), + ...fields.slice(position - 1, position + 1).reverse(), + ...fields.slice(position + 1) + ]); + }; + const isFull = fields.length >= CUSTOM_FIELDS_MAX_FIELD_COUNT; + + return ( +
+ + onChange({ ...value, label })} + /> +
+ {t({ en: 'Fields', es: 'Campos', fr: 'Champs' })} +

+ {t({ + en: 'Staff fill in every field, in this order, to identify a subject.', + es: 'El personal completa todos los campos, en este orden, para identificar a un sujeto.', + fr: 'Le personnel remplit chaque champ, dans cet ordre, pour identifier un sujet.' + })} +

+

+ {t({ + en: 'A label may be corrected, but never given a new meaning: renaming "Animal ID" to "Cage number" would have staff type something else, which identifies a different subject.', + es: 'Una etiqueta puede corregirse, pero nunca cambiar de significado: renombrar «ID del animal» como «Número de jaula» haría que el personal escribiera otra cosa, lo que identifica a otro sujeto.', + fr: "Une étiquette peut être corrigée, mais jamais changer de sens : renommer « ID de l'animal » en « Numéro de cage » amènerait le personnel à saisir autre chose, ce qui identifie un autre sujet." + })} +

+ {fields.map((field, position) => ( + raiseField(position + 1)} + onMoveUp={() => raiseField(position)} + onRemove={() => updateFields(fields.filter((_, index) => index !== position))} + /> + ) + } + position={position} + showErrors={showErrors} + value={field} + onChange={(next) => updateFields(fields.map((current, index) => (index === position ? next : current)))} + /> + ))} + {!isLocked && ( +
+ + {isFull && ( +

+ {t( + { + en: 'A definition has at most {} fields.', + es: 'Una definición tiene como máximo {} campos.', + fr: 'Une définition compte au plus {} champs.' + }, + { args: [CUSTOM_FIELDS_MAX_FIELD_COUNT] } + )} +

+ )} +
+ )} +
+ {!isLocked && ( +
+ +

+ {t({ + en: 'Until a subject has been identified with these fields, the whole definition can be removed. It is removed when you save.', + es: 'Mientras no se haya identificado ningún sujeto con estos campos, se puede eliminar toda la definición. Se elimina al guardar.', + fr: "Tant qu'aucun sujet n'a été identifié avec ces champs, la définition entière peut être supprimée. Elle l'est à l'enregistrement." + })} +

+
+ )} +
+ ); +}; + +export type CustomFieldsEditorProps = { + activeLanguages: readonly Language[]; + /** Whether a definition is saved, which a draft of `null` removes when the tab is saved. */ + isDefinitionStored: boolean; + isLocked: boolean; + onChange: (value: CustomFieldsDraft | null) => void; + /** Shows every missing entry as an error, once a save has been refused for one. */ + showErrors: boolean; + value: CustomFieldsDraft | null; +}; + +/** The admin's definition of the fields that identify a subject under the `CUSTOM_FIELDS` method. */ +export const CustomFieldsEditor = ({ + activeLanguages, + isDefinitionStored, + isLocked, + onChange, + showErrors, + value +}: CustomFieldsEditorProps) => { + const { t } = useTranslation(); + return ( + + + {t({ + en: 'Custom Identifying Fields', + es: 'Campos de identificación personalizados', + fr: "Champs d'identification personnalisés" + })} + +

+ {t({ + en: "Define the fields staff fill in to identify a subject, such as an animal or record number. What they type is hashed in the browser into the subject's id, and is never sent or stored.", + es: 'Defina los campos que el personal completa para identificar a un sujeto, como un número de animal o de expediente. Lo que escribe se convierte en el navegador, mediante un hash, en el identificador del sujeto, y nunca se envía ni se almacena.', + fr: "Définissez les champs que le personnel remplit pour identifier un sujet, comme un numéro d'animal ou de dossier. Ce qu'il saisit est haché dans le navigateur pour former l'identifiant du sujet, et n'est jamais envoyé ni stocké." + })} +

+ {value ? ( + + ) : ( +
+

+ {isDefinitionStored + ? t({ + en: 'The identifying fields will be removed when you save.', + es: 'Los campos de identificación se eliminarán al guardar.', + fr: "Les champs d'identification seront supprimés à l'enregistrement." + }) + : t({ + en: 'No identifying fields are defined.', + es: 'No hay campos de identificación definidos.', + fr: "Aucun champ d'identification n'est défini." + })} +

+ +
+ )} +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/LocalizedTextInputs.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/LocalizedTextInputs.tsx new file mode 100644 index 000000000..cc21b22ad --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/LocalizedTextInputs.tsx @@ -0,0 +1,67 @@ +import { Input, Label } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { Language, LocalizedString } from '@opendatacapture/schemas/core'; + +import { LANGUAGE_LABELS } from '@/utils/language'; + +export type LocalizedTextInputsProps = { + description?: string; + /** Each input's id and test id is this followed by the input's language, e.g. `custom-fields-label-en`. */ + idPrefix: string; + /** Says that the text is required in some language and is written in none. */ + isMissing?: boolean; + label: string; + languages: readonly Language[]; + onChange: (value: LocalizedString) => void; + value: LocalizedString | null | undefined; +}; + +/** + * One text input per language. Text in a language not offered here is kept, so turning a language + * off and back on does not lose what was written in it. + */ +export const LocalizedTextInputs = ({ + description, + idPrefix, + isMissing, + label, + languages, + onChange, + value +}: LocalizedTextInputsProps) => { + const { t } = useTranslation(); + return ( +
+

+ {label} +

+ {description &&

{description}

} + {languages.map((language) => ( +
+ + onChange({ ...value, [language]: event.target.value })} + /> +
+ ))} + {isMissing && ( +

+ {t({ + en: 'Enter this in at least one language.', + es: 'Introdúzcalo en al menos un idioma.', + fr: 'Saisissez-le dans au moins une langue.' + })} +

+ )} +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx new file mode 100644 index 000000000..69a230b74 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx @@ -0,0 +1,166 @@ +import { useState } from 'react'; + +import { Button, Dialog } from '@douglasneuroinformatics/libui/components'; +import { useNotificationsStore, useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { Language } from '@opendatacapture/schemas/core'; +import { $UpdateSubjectIdentificationSettingsData } from '@opendatacapture/schemas/subject-identification'; +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { useQueryClient } from '@tanstack/react-query'; +import { isAxiosError } from 'axios'; +import { Loader2Icon } from 'lucide-react'; + +import { subjectIdentificationSettingsQueryOptions } from '@/hooks/useSubjectIdentificationSettingsQuery'; +import { useUpdateSubjectIdentificationSettingsMutation } from '@/hooks/useUpdateSubjectIdentificationSettingsMutation'; +import { + toSubjectIdentificationDraft, + toUpdateSubjectIdentificationSettingsData +} from '@/utils/subject-identification-draft'; +import type { SubjectIdentificationDraft } from '@/utils/subject-identification-draft'; + +import { CustomFieldsEditor } from './CustomFieldsEditor'; + +export type SubjectIdentificationSettingsFormProps = { + activeLanguages: readonly Language[]; + settings: SubjectIdentificationSettings; +}; + +/** + * The Subject Identification tab's one form. Every section edits its part of one draft, and the + * save button sends the whole draft in one request. + */ +export const SubjectIdentificationSettingsForm = ({ + activeLanguages, + settings +}: SubjectIdentificationSettingsFormProps) => { + const { t } = useTranslation(); + const addNotification = useNotificationsStore((store) => store.addNotification); + const queryClient = useQueryClient(); + const updateMutation = useUpdateSubjectIdentificationSettingsMutation(); + const [draft, setDraft] = useState(() => toSubjectIdentificationDraft(settings)); + const [showErrors, setShowErrors] = useState(false); + const [isConfirmationOpen, setIsConfirmationOpen] = useState(false); + + const updateData = toUpdateSubjectIdentificationSettingsData(draft); + const isValid = $UpdateSubjectIdentificationSettingsData.safeParse(updateData).success; + + const save = async () => { + const saveFailedTitle = t({ en: 'Save failed', es: 'Error al guardar', fr: "Échec de l'enregistrement" }); + try { + await updateMutation.mutateAsync(updateData); + setShowErrors(false); + addNotification({ type: 'success' }); + } catch (error) { + // The server answers 409 only to a change the lock forbids, so a subject was identified with the + // fields after this page loaded, and the draft's field list can never be saved. + if (!(isAxiosError(error) && error.response?.status === 409)) { + addNotification({ + message: t({ + en: 'Your changes were not saved. Check your connection and try again.', + es: 'Sus cambios no se guardaron. Compruebe su conexión e inténtelo de nuevo.', + fr: "Vos modifications n'ont pas été enregistrées. Vérifiez votre connexion et réessayez." + }), + title: saveFailedTitle, + type: 'error' + }); + return; + } + addNotification({ + message: t({ + en: 'A subject was identified with these fields while you were editing, so the field list is now locked. The saved definition has been reloaded; make your other changes again.', + es: 'Se identificó a un sujeto con estos campos mientras usted editaba, por lo que la lista de campos está ahora bloqueada. Se ha vuelto a cargar la definición guardada; vuelva a hacer sus demás cambios.', + fr: 'Un sujet a été identifié avec ces champs pendant votre édition : la liste des champs est désormais verrouillée. La définition enregistrée a été rechargée ; refaites vos autres modifications.' + }), + title: saveFailedTitle, + type: 'error' + }); + setDraft(toSubjectIdentificationDraft(await queryClient.fetchQuery(subjectIdentificationSettingsQueryOptions()))); + } + }; + + const handleSave = () => { + if (!isValid) { + setShowErrors(true); + } else if (settings.customFields === null && draft.customFields !== null) { + setIsConfirmationOpen(true); + } else { + void save(); + } + }; + + const handleConfirm = () => { + setIsConfirmationOpen(false); + void save(); + }; + + return ( +
+ setDraft((current) => ({ ...current, customFields }))} + /> +
+ + {showErrors && !isValid && ( +

+ {t({ + en: 'Complete the entries marked above, then save again.', + es: 'Complete las entradas señaladas arriba y vuelva a guardar.', + fr: 'Complétez les entrées signalées ci-dessus, puis enregistrez de nouveau.' + })} +

+ )} +
+ + + + + {t({ + en: 'Save the identifying fields?', + es: '¿Guardar los campos de identificación?', + fr: "Enregistrer les champs d'identification ?" + })} + + + {t({ + en: 'Once a subject has been identified with these fields, the field list cannot change: no field can be added, removed or moved, and the definition cannot be removed. Labels, help text, patterns and error messages stay editable.', + es: 'Una vez que se haya identificado a un sujeto con estos campos, la lista de campos no podrá cambiar: no se podrá agregar, eliminar ni mover ningún campo, ni eliminar la definición. Las etiquetas, los textos de ayuda, los patrones y los mensajes de error seguirán siendo editables.', + fr: "Dès qu'un sujet aura été identifié avec ces champs, la liste des champs ne pourra plus changer : aucun champ ne pourra être ajouté, supprimé ou déplacé, et la définition ne pourra plus être supprimée. Les étiquettes, les textes d'aide, les motifs et les messages d'erreur resteront modifiables." + })} + + + + + + + + +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldEditor.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldEditor.test.tsx new file mode 100644 index 000000000..473d048e8 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldEditor.test.tsx @@ -0,0 +1,95 @@ +import { cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import type { CustomFieldDraft } from '@/utils/subject-identification-draft'; + +import { CustomFieldEditor } from '../CustomFieldEditor'; + +import '@/services/i18n'; + +const field: CustomFieldDraft = { key: 'field', label: { en: 'Animal ID' }, pattern: '[A-Z]{2}[0-9]+' }; + +const renderEditor = (value: CustomFieldDraft = field, { showErrors = false } = {}) => { + const onChange = vi.fn<(field: CustomFieldDraft) => void>(); + render( + } + position={1} + showErrors={showErrors} + value={value} + onChange={onChange} + /> + ); + return onChange; +}; + +const type = (testId: string, value: string) => fireEvent.change(screen.getByTestId(testId), { target: { value } }); + +describe('CustomFieldEditor', () => { + afterEach(cleanup); + + it('should name its inputs after its position, so a test can drive a field by where it is', () => { + renderEditor(); + expect(screen.getByTestId('custom-field-1-label-en').value).toBe('Animal ID'); + expect(screen.getByTestId('custom-field-1-pattern').value).toBe('[A-Z]{2}[0-9]+'); + }); + + it('should show the list controls it is given beside its heading', () => { + renderEditor(); + expect(screen.getByTestId('list-controls')).toBeTruthy(); + }); + + it('should report an edited label', () => { + const onChange = renderEditor(); + type('custom-field-1-label-fr', "ID de l'animal"); + expect(onChange).toHaveBeenCalledWith({ ...field, label: { en: 'Animal ID', fr: "ID de l'animal" } }); + }); + + it('should report edited help text', () => { + const onChange = renderEditor(); + type('custom-field-1-help-en', 'On the cage card'); + expect(onChange).toHaveBeenCalledWith({ ...field, description: { en: 'On the cage card' } }); + }); + + it('should report an edited pattern', () => { + const onChange = renderEditor(); + type('custom-field-1-pattern', '[0-9]+'); + expect(onChange).toHaveBeenCalledWith({ ...field, pattern: '[0-9]+' }); + }); + + it('should report an edited error message', () => { + const onChange = renderEditor(); + type('custom-field-1-error-message-en', 'Two letters, then digits'); + expect(onChange).toHaveBeenCalledWith({ ...field, patternErrorMessage: { en: 'Two letters, then digits' } }); + }); + + it('should say a pattern does not compile as soon as it is typed', () => { + renderEditor({ ...field, pattern: '[A-Z' }); + expect(screen.getByTestId('custom-field-1-pattern-error')).toBeTruthy(); + }); + + it('should leave a missing label and pattern unflagged until a save is refused', () => { + renderEditor({ ...field, label: {}, pattern: '' }); + expect(screen.queryByTestId('custom-field-1-label-error')).toBeNull(); + expect(screen.queryByTestId('custom-field-1-pattern-error')).toBeNull(); + }); + + it('should flag a missing label and pattern once a save is refused', () => { + renderEditor({ ...field, label: {}, pattern: '' }, { showErrors: true }); + expect(screen.getByTestId('custom-field-1-label-error')).toBeTruthy(); + expect(screen.getByTestId('custom-field-1-pattern-error')).toBeTruthy(); + }); + + it('should test a sample against the field pattern', () => { + renderEditor(); + type('custom-field-1-test-input', 'ab-1234'); + expect(screen.getByTestId('custom-field-1-test-result').dataset.verdict).toBe('accepted'); + }); + + it('should not test a sample against a pattern that does not compile', () => { + renderEditor({ ...field, pattern: '[A-Z' }); + type('custom-field-1-test-input', 'ab-1234'); + expect(screen.getByTestId('custom-field-1-test-result').dataset.verdict).toBe('no-pattern'); + }); +}); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldTestBox.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldTestBox.test.tsx new file mode 100644 index 000000000..32cf3c0c1 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldTestBox.test.tsx @@ -0,0 +1,61 @@ +import { compileCustomFieldPattern } from '@opendatacapture/schemas/subject-identification'; +import { cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, describe, expect, it } from 'vitest'; + +import { CustomFieldTestBox } from '../CustomFieldTestBox'; + +import '@/services/i18n'; + +const renderTestBox = (pattern: null | string = '[A-Z]{2}[0-9]+') => { + const compiledPattern = pattern === null ? null : compileCustomFieldPattern(pattern); + render(); +}; + +const typeSample = (value: string) => fireEvent.change(screen.getByTestId('test-input'), { target: { value } }); + +const verdict = () => screen.getByTestId('test-result').dataset.verdict; + +describe('CustomFieldTestBox', () => { + afterEach(cleanup); + + it('should show no result before a value is typed', () => { + renderTestBox(); + expect(screen.queryByTestId('test-result')).toBeNull(); + }); + + it('should show the value as the pattern sees it, uppercased with only letters and digits left', () => { + renderTestBox(); + typeSample('ab-12 34'); + expect(screen.getByTestId('test-normalized').textContent).toBe('AB1234'); + }); + + it('should accept a value whose normalized form the pattern matches in full', () => { + renderTestBox(); + typeSample('ab-1234'); + expect(verdict()).toBe('accepted'); + }); + + it('should reject a value the pattern matches only in part', () => { + renderTestBox(); + typeSample('ab-1234-x'); + expect(verdict()).toBe('rejected'); + }); + + it('should refuse a value with no letters or digits, since the forms refuse it', () => { + renderTestBox(); + typeSample('- -'); + expect(verdict()).toBe('normalizes-to-nothing'); + }); + + it('should refuse a value longer than the forms accept, whatever the pattern says', () => { + renderTestBox('[A-Z]+'); + typeSample('A'.repeat(201)); + expect(verdict()).toBe('too-long'); + }); + + it('should ask for a valid pattern when the field has none to test against', () => { + renderTestBox(null); + typeSample('ab-1234'); + expect(verdict()).toBe('no-pattern'); + }); +}); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx new file mode 100644 index 000000000..039da03b6 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx @@ -0,0 +1,180 @@ +import { useState } from 'react'; + +import { CUSTOM_FIELDS_MAX_FIELD_COUNT } from '@opendatacapture/schemas/subject-identification'; +import { cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import type { CustomFieldDraft, CustomFieldsDraft } from '@/utils/subject-identification-draft'; + +import { CustomFieldsEditor } from '../CustomFieldsEditor'; + +import '@/services/i18n'; + +const field = (name: string): CustomFieldDraft => ({ key: name, label: { en: name }, pattern: '[0-9]+' }); + +const definition = (...names: string[]): CustomFieldsDraft => ({ + fields: names.map(field), + label: { en: 'Animal information' } +}); + +type EditorOptions = { + isDefinitionStored?: boolean; + isLocked?: boolean; + showErrors?: boolean; +}; + +const renderEditor = ( + initial: CustomFieldsDraft | null, + { isDefinitionStored = initial !== null, isLocked = false, showErrors = false }: EditorOptions = {} +) => { + const onChange = vi.fn<(value: CustomFieldsDraft | null) => void>(); + const Harness = () => { + const [value, setValue] = useState(initial); + return ( + { + onChange(next); + setValue(next); + }} + /> + ); + }; + render(); + return onChange; +}; + +const click = (testId: string) => fireEvent.click(screen.getByTestId(testId)); + +const fieldLabels = () => { + return screen.queryAllByTestId(/^custom-field-\d+-label-en$/).map((input) => input.value); +}; + +const isDisabled = (testId: string) => screen.getByTestId(testId).disabled; + +describe('CustomFieldsEditor', () => { + afterEach(cleanup); + + describe('without a definition', () => { + it('should say that none is defined', () => { + renderEditor(null); + expect(screen.getByTestId('custom-fields-empty').textContent).toBe('No identifying fields are defined.'); + }); + + it('should start a definition with one field to fill in', () => { + renderEditor(null); + click('custom-fields-define'); + expect(fieldLabels()).toStrictEqual(['']); + }); + + it('should say that a stored definition the admin removed goes when the tab is saved', () => { + renderEditor(null, { isDefinitionStored: true }); + expect(screen.getByTestId('custom-fields-empty').textContent).toBe( + 'The identifying fields will be removed when you save.' + ); + }); + }); + + describe('while unlocked', () => { + it('should say the definition is not locked', () => { + renderEditor(definition('A')); + expect(screen.getByTestId('custom-fields-lock-status').dataset.locked).toBe('false'); + }); + + it('should add a blank field at the end', () => { + renderEditor(definition('A')); + click('custom-fields-add-field'); + expect(fieldLabels()).toStrictEqual(['A', '']); + }); + + it('should not add a field beyond the limit', () => { + renderEditor(definition(...Array.from({ length: CUSTOM_FIELDS_MAX_FIELD_COUNT }, (_, index) => `F${index}`))); + expect(isDisabled('custom-fields-add-field')).toBe(true); + expect(screen.getByTestId('custom-fields-full')).toBeTruthy(); + }); + + it('should move a field up', () => { + renderEditor(definition('A', 'B', 'C')); + click('custom-field-2-move-up'); + expect(fieldLabels()).toStrictEqual(['A', 'C', 'B']); + }); + + it('should move a field down', () => { + renderEditor(definition('A', 'B', 'C')); + click('custom-field-0-move-down'); + expect(fieldLabels()).toStrictEqual(['B', 'A', 'C']); + }); + + it('should not move the first field up or the last field down', () => { + renderEditor(definition('A', 'B')); + expect(isDisabled('custom-field-0-move-up')).toBe(true); + expect(isDisabled('custom-field-1-move-down')).toBe(true); + }); + + it('should remove a field', () => { + renderEditor(definition('A', 'B', 'C')); + click('custom-field-1-remove'); + expect(fieldLabels()).toStrictEqual(['A', 'C']); + }); + + it('should not remove the only field, since a definition has at least one', () => { + renderEditor(definition('A')); + expect(isDisabled('custom-field-0-remove')).toBe(true); + }); + + it('should edit the field whose input changed and leave the others alone', () => { + renderEditor(definition('A', 'B')); + fireEvent.change(screen.getByTestId('custom-field-1-label-en'), { target: { value: 'Cage' } }); + expect(fieldLabels()).toStrictEqual(['A', 'Cage']); + }); + + it('should edit the method label', () => { + const onChange = renderEditor(definition('A')); + fireEvent.change(screen.getByTestId('custom-fields-label-en'), { target: { value: 'Mouse' } }); + expect(onChange.mock.lastCall?.[0]?.label).toStrictEqual({ en: 'Mouse' }); + }); + + it('should remove the whole definition', () => { + const onChange = renderEditor(definition('A')); + click('custom-fields-remove'); + expect(onChange).toHaveBeenCalledWith(null); + }); + }); + + describe('once locked', () => { + it('should say the definition is locked', () => { + renderEditor(definition('A'), { isLocked: true }); + expect(screen.getByTestId('custom-fields-lock-status').dataset.locked).toBe('true'); + }); + + it('should offer no way to add, move or remove a field, or to remove the definition', () => { + renderEditor(definition('A', 'B'), { isLocked: true }); + expect(screen.queryByTestId('custom-fields-add-field')).toBeNull(); + expect(screen.queryByTestId('custom-field-0-move-down')).toBeNull(); + expect(screen.queryByTestId('custom-field-0-remove')).toBeNull(); + expect(screen.queryByTestId('custom-fields-remove')).toBeNull(); + }); + + it('should still let a field be edited, since no field text is hashed', () => { + renderEditor(definition('A'), { isLocked: true }); + fireEvent.change(screen.getByTestId('custom-field-0-pattern'), { target: { value: '[A-Z]+' } }); + expect(screen.getByTestId('custom-field-0-pattern').value).toBe('[A-Z]+'); + }); + }); + + describe('errors', () => { + it('should flag a missing method label once a save is refused', () => { + renderEditor({ ...definition('A'), label: {} }, { showErrors: true }); + expect(screen.getByTestId('custom-fields-label-error')).toBeTruthy(); + }); + + it('should not flag a missing method label before a save is refused', () => { + renderEditor({ ...definition('A'), label: {} }); + expect(screen.queryByTestId('custom-fields-label-error')).toBeNull(); + }); + }); +}); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/LocalizedTextInputs.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/LocalizedTextInputs.test.tsx new file mode 100644 index 000000000..091e7a248 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/LocalizedTextInputs.test.tsx @@ -0,0 +1,52 @@ +import type { LocalizedString } from '@opendatacapture/schemas/core'; +import { cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { LocalizedTextInputs } from '../LocalizedTextInputs'; + +import '@/services/i18n'; + +const renderInputs = (value: LocalizedString | undefined, props: { isMissing?: boolean } = {}) => { + const onChange = vi.fn<(value: LocalizedString) => void>(); + render( + + ); + return onChange; +}; + +const input = (testId: string) => screen.getByTestId(testId); + +describe('LocalizedTextInputs', () => { + afterEach(cleanup); + + it('should show one input per offered language, holding the text written in it', () => { + renderInputs({ en: 'Animal ID' }); + expect(input('label-en').value).toBe('Animal ID'); + expect(input('label-fr').value).toBe(''); + expect(screen.queryByTestId('label-es')).toBeNull(); + }); + + it('should keep text in a language not offered when another is edited, so turning a language off loses nothing', () => { + const onChange = renderInputs({ en: 'Animal ID', es: 'ID del animal' }); + fireEvent.change(input('label-fr'), { target: { value: "ID de l'animal" } }); + expect(onChange).toHaveBeenCalledWith({ en: 'Animal ID', es: 'ID del animal', fr: "ID de l'animal" }); + }); + + it('should ask for the text in some language when it is missing', () => { + renderInputs(undefined, { isMissing: true }); + expect(screen.getByTestId('label-error').textContent).toBe('Enter this in at least one language.'); + }); + + it('should show no error when the text is not missing', () => { + renderInputs(undefined); + expect(screen.queryByTestId('label-error')).toBeNull(); + }); +}); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx new file mode 100644 index 000000000..5f0f63859 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx @@ -0,0 +1,198 @@ +import { useNotificationsStore } from '@douglasneuroinformatics/libui/hooks'; +import type { + $UpdateSubjectIdentificationSettingsData, + SubjectIdentificationSettings +} from '@opendatacapture/schemas/subject-identification'; +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'; +import { AxiosError, AxiosHeaders } from 'axios'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { SubjectIdentificationSettingsForm } from '../SubjectIdentificationSettingsForm'; + +import '@/services/i18n'; + +const mockAxios = vi.hoisted(() => ({ get: vi.fn(), put: vi.fn() })); + +vi.mock('axios', async (importOriginal) => ({ + ...(await importOriginal()), + default: mockAxios +})); + +const SALT = 'ab'.repeat(32); + +const storedSettings = (overrides: Partial = {}): SubjectIdentificationSettings => ({ + customFields: { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 600_000, + label: { en: 'Animal information' }, + salt: SALT + }, + isCustomFieldsLocked: false, + ...overrides +}); + +const unsetSettings: SubjectIdentificationSettings = { customFields: null, isCustomFieldsLocked: false }; + +const conflictError = () => { + return new AxiosError('Conflict', 'ERR_BAD_REQUEST', undefined, undefined, { + config: { headers: new AxiosHeaders() }, + data: {}, + headers: {}, + status: 409, + statusText: 'Conflict' + }); +}; + +const renderForm = (settings: SubjectIdentificationSettings) => { + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + render( + + + + ); +}; + +const click = (testId: string) => fireEvent.click(screen.getByTestId(testId)); +const type = (testId: string, value: string) => fireEvent.change(screen.getByTestId(testId), { target: { value } }); +const lastPutBody = (): unknown => mockAxios.put.mock.lastCall?.[1]; +const lastNotification = () => useNotificationsStore.getState().notifications.at(-1); + +const defineOneField = () => { + click('custom-fields-define'); + type('custom-fields-label-en', 'Animal information'); + type('custom-field-0-label-en', 'Animal ID'); + type('custom-field-0-pattern', '[0-9]+'); +}; + +describe('SubjectIdentificationSettingsForm', () => { + beforeEach(() => { + vi.clearAllMocks(); + mockAxios.put.mockImplementation((_url, { customFields }: $UpdateSubjectIdentificationSettingsData) => { + const saved = customFields && { ...customFields, iterations: 600_000, salt: SALT }; + return Promise.resolve({ data: { customFields: saved, isCustomFieldsLocked: false } }); + }); + useNotificationsStore.setState({ notifications: [] }); + }); + + afterEach(cleanup); + + describe('the first definition', () => { + it('should ask for confirmation before saving, since the field list is fixed once a subject is identified', () => { + renderForm(unsetSettings); + defineOneField(); + click('subject-identification-save'); + expect(screen.getByTestId('subject-identification-confirm-dialog')).toBeTruthy(); + expect(mockAxios.put).not.toHaveBeenCalled(); + }); + + it('should save the definition once confirmed', async () => { + renderForm(unsetSettings); + defineOneField(); + click('subject-identification-save'); + click('subject-identification-confirm-save'); + await waitFor(() => expect(lastNotification()?.type).toBe('success')); + expect(lastPutBody()).toStrictEqual({ + customFields: { + fields: [{ description: null, label: { en: 'Animal ID' }, pattern: '[0-9]+', patternErrorMessage: null }], + label: { en: 'Animal information' } + } + }); + }); + + it('should not save when the confirmation is cancelled', () => { + renderForm(unsetSettings); + defineOneField(); + click('subject-identification-save'); + click('subject-identification-cancel-save'); + expect(screen.queryByTestId('subject-identification-confirm-dialog')).toBeNull(); + expect(mockAxios.put).not.toHaveBeenCalled(); + }); + + it('should save without confirmation while still no definition is drafted', async () => { + renderForm(unsetSettings); + click('subject-identification-save'); + await waitFor(() => expect(lastPutBody()).toStrictEqual({ customFields: null })); + }); + }); + + describe('an incomplete definition', () => { + it('should not save it, and flag what is missing', () => { + renderForm(unsetSettings); + click('custom-fields-define'); + click('subject-identification-save'); + expect(screen.getByTestId('subject-identification-invalid')).toBeTruthy(); + expect(screen.getByTestId('custom-fields-label-error')).toBeTruthy(); + expect(screen.getByTestId('custom-field-0-label-error')).toBeTruthy(); + expect(screen.queryByTestId('subject-identification-confirm-dialog')).toBeNull(); + expect(mockAxios.put).not.toHaveBeenCalled(); + }); + + it('should stop flagging missing entries once a save succeeds, so a field added later starts clean', async () => { + renderForm(storedSettings()); + type('custom-fields-label-en', ''); + click('subject-identification-save'); + type('custom-fields-label-en', 'Mouse'); + click('subject-identification-save'); + await waitFor(() => expect(lastNotification()?.type).toBe('success')); + click('custom-fields-add-field'); + expect(screen.queryByTestId('custom-field-1-label-error')).toBeNull(); + }); + }); + + describe('a stored definition', () => { + it('should save an edit without asking for confirmation', async () => { + renderForm(storedSettings()); + type('custom-field-0-label-fr', "ID de l'animal"); + click('subject-identification-save'); + await waitFor(() => expect(lastNotification()?.type).toBe('success')); + expect(screen.queryByTestId('subject-identification-confirm-dialog')).toBeNull(); + expect(lastPutBody()).toMatchObject({ + customFields: { fields: [{ label: { en: 'Animal ID', fr: "ID de l'animal" } }] } + }); + }); + + it('should save a removed definition as null', async () => { + renderForm(storedSettings()); + click('custom-fields-remove'); + click('subject-identification-save'); + await waitFor(() => expect(lastPutBody()).toStrictEqual({ customFields: null })); + }); + + it('should not offer a second save while one is in flight', async () => { + // A save that never settles holds the form in flight for the whole test. + mockAxios.put.mockReturnValue(Promise.race([])); + renderForm(storedSettings()); + click('subject-identification-save'); + await waitFor(() => { + expect(screen.getByTestId('subject-identification-save').disabled).toBe(true); + }); + }); + }); + + describe('a failed save', () => { + it('should say the changes were not saved and keep them', async () => { + mockAxios.put.mockRejectedValue(new Error('Network Error')); + renderForm(storedSettings()); + type('custom-field-0-label-en', 'Mouse ID'); + click('subject-identification-save'); + await waitFor(() => expect(lastNotification()?.type).toBe('error')); + expect(screen.getByTestId('custom-field-0-label-en').value).toBe('Mouse ID'); + }); + + // A conflict means a subject was identified with the fields after the page loaded, so the field + // list in the draft can never be saved and the lock must now show. + it('should reload the saved definition when the fields locked while they were being edited', async () => { + mockAxios.put.mockRejectedValue(conflictError()); + mockAxios.get.mockResolvedValue({ data: storedSettings({ isCustomFieldsLocked: true }) }); + renderForm(storedSettings()); + click('custom-fields-add-field'); + type('custom-field-1-label-en', 'Cage'); + type('custom-field-1-pattern', '[0-9]+'); + click('subject-identification-save'); + await waitFor(() => expect(screen.queryByTestId('custom-field-1')).toBeNull()); + expect(mockAxios.get).toHaveBeenCalledWith('/v1/subjects/identification/settings'); + expect(lastNotification()?.type).toBe('error'); + }); + }); +}); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/index.ts b/apps/web/src/components/SubjectIdentificationSettingsForm/index.ts new file mode 100644 index 000000000..874881845 --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/index.ts @@ -0,0 +1 @@ +export * from './SubjectIdentificationSettingsForm'; diff --git a/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts b/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts new file mode 100644 index 000000000..48380546e --- /dev/null +++ b/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts @@ -0,0 +1,55 @@ +import type { PropsWithChildren } from 'react'; +import { createElement } from 'react'; + +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { renderHook } from '@testing-library/react'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +import { useUpdateSubjectIdentificationSettingsMutation } from '../useUpdateSubjectIdentificationSettingsMutation'; + +const mockAxios = vi.hoisted(() => ({ isAxiosError: vi.fn(() => false), put: vi.fn() })); + +vi.mock('axios', () => ({ default: mockAxios })); + +const definition = { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + label: { en: 'Animal information' } +}; + +const savedSettings = { + customFields: { ...definition, iterations: 600_000, salt: 'ab'.repeat(32) }, + isCustomFieldsLocked: false +}; + +function renderUpdateMutation() { + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + const wrapper = ({ children }: PropsWithChildren) => { + return createElement(QueryClientProvider, { children, client: queryClient }); + }; + return { ...renderHook(() => useUpdateSubjectIdentificationSettingsMutation(), { wrapper }), queryClient }; +} + +describe('useUpdateSubjectIdentificationSettingsMutation', () => { + beforeEach(() => { + vi.clearAllMocks(); + mockAxios.put.mockResolvedValue({ data: savedSettings }); + }); + + it('should put the settings without raising the default error toast, since the tab says why a save failed', async () => { + const { result } = renderUpdateMutation(); + await result.current.mutateAsync({ customFields: definition }); + expect(mockAxios.put).toHaveBeenCalledWith( + '/v1/subjects/identification/settings', + { customFields: definition }, + { meta: { disableDefaultErrorNotification: true } } + ); + }); + + // The tab asks for confirmation only while no definition is stored, so the cache must hold the + // saved definition as soon as the first save returns. + it('should seed the settings cache from the response', async () => { + const { queryClient, result } = renderUpdateMutation(); + await result.current.mutateAsync({ customFields: definition }); + expect(queryClient.getQueryData(['subject-identification-settings'])).toStrictEqual(savedSettings); + }); +}); diff --git a/apps/web/src/hooks/useUpdateSubjectIdentificationSettingsMutation.ts b/apps/web/src/hooks/useUpdateSubjectIdentificationSettingsMutation.ts new file mode 100644 index 000000000..e12b36b79 --- /dev/null +++ b/apps/web/src/hooks/useUpdateSubjectIdentificationSettingsMutation.ts @@ -0,0 +1,27 @@ +import { $SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import type { $UpdateSubjectIdentificationSettingsData } from '@opendatacapture/schemas/subject-identification'; +import { useMutation, useQueryClient } from '@tanstack/react-query'; +import axios from 'axios'; + +import { subjectIdentificationSettingsQueryOptions } from './useSubjectIdentificationSettingsQuery'; + +// The Subject Identification tab says itself why a save failed, so this mutation raises no error +// toast and does not escape to the router error boundary: a failed save must leave the admin on the +// page with their unsaved edits, which means the caller has to see the rejection. +export function useUpdateSubjectIdentificationSettingsMutation() { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: async (data: $UpdateSubjectIdentificationSettingsData) => { + const response = await axios.put('/v1/subjects/identification/settings', data, { + meta: { disableDefaultErrorNotification: true } + }); + return $SubjectIdentificationSettings.parseAsync(response.data); + }, + onSuccess(data) { + // Seeded from the response rather than invalidated: the tab decides whether to ask for + // confirmation from whether a definition is stored, which must be true right after the first save. + queryClient.setQueryData(subjectIdentificationSettingsQueryOptions().queryKey, data); + }, + throwOnError: false + }); +} diff --git a/apps/web/src/utils/__tests__/subject-identification-draft.test.ts b/apps/web/src/utils/__tests__/subject-identification-draft.test.ts new file mode 100644 index 000000000..ad7cd14fb --- /dev/null +++ b/apps/web/src/utils/__tests__/subject-identification-draft.test.ts @@ -0,0 +1,122 @@ +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { describe, expect, it } from 'vitest'; + +import { + createCustomFieldDraft, + createCustomFieldsDraft, + findCustomFieldIssues, + isCustomFieldsLabelMissing, + toSubjectIdentificationDraft, + toUpdateSubjectIdentificationSettingsData +} from '../subject-identification-draft'; + +import type { CustomFieldDraft } from '../subject-identification-draft'; + +const settings: SubjectIdentificationSettings = { + customFields: { + fields: [ + { label: { en: 'Animal ID' }, pattern: '[0-9]+' }, + { description: { fr: 'Numéro de la cage' }, label: { en: 'Cage' }, pattern: '[A-Z]+' } + ], + iterations: 600_000, + label: { en: 'Animal information' }, + salt: 'ab'.repeat(32) + }, + isCustomFieldsLocked: false +}; + +const field = (overrides: Partial = {}): CustomFieldDraft => ({ + key: 'field', + label: { en: 'Animal ID' }, + pattern: '[0-9]+', + ...overrides +}); + +describe('createCustomFieldDraft', () => { + it('should give each new field its own key, so two new fields keep their own inputs when reordered', () => { + expect(createCustomFieldDraft().key).not.toBe(createCustomFieldDraft().key); + }); +}); + +describe('createCustomFieldsDraft', () => { + it('should start a definition with one blank field, since a definition has at least one', () => { + expect(createCustomFieldsDraft()).toMatchObject({ fields: [{ label: {}, pattern: '' }], label: {} }); + }); +}); + +describe('toSubjectIdentificationDraft', () => { + it('should keep the stored fields in order, each with its own key', () => { + const draft = toSubjectIdentificationDraft(settings); + expect(draft.customFields?.fields.map(({ label }) => label.en)).toStrictEqual(['Animal ID', 'Cage']); + expect(new Set(draft.customFields?.fields.map(({ key }) => key)).size).toBe(2); + }); + + it('should leave out the salt and iteration count, which only the server sets', () => { + expect(toSubjectIdentificationDraft(settings).customFields).not.toHaveProperty('salt'); + }); + + it('should hold no definition when none is stored', () => { + expect(toSubjectIdentificationDraft({ customFields: null, isCustomFieldsLocked: false })).toStrictEqual({ + customFields: null + }); + }); +}); + +describe('toUpdateSubjectIdentificationSettingsData', () => { + it('should send the fields without their keys and with blank languages left out', () => { + const data = toUpdateSubjectIdentificationSettingsData({ + customFields: { fields: [field({ label: { en: 'Animal ID', fr: ' ' } })], label: { en: 'Animal', es: '' } } + }); + expect(data).toStrictEqual({ + customFields: { + fields: [{ description: null, label: { en: 'Animal ID' }, pattern: '[0-9]+', patternErrorMessage: null }], + label: { en: 'Animal' } + } + }); + }); + + it('should send optional text written in any language', () => { + const data = toUpdateSubjectIdentificationSettingsData({ + customFields: { + fields: [field({ description: { fr: 'Aide' }, patternErrorMessage: { es: 'Error' } })], + label: {} + } + }); + expect(data.customFields?.fields[0]).toMatchObject({ + description: { fr: 'Aide' }, + patternErrorMessage: { es: 'Error' } + }); + }); + + it('should send a removed definition as null', () => { + expect(toUpdateSubjectIdentificationSettingsData({ customFields: null })).toStrictEqual({ customFields: null }); + }); +}); + +describe('findCustomFieldIssues', () => { + it('should find nothing wrong with a labelled field whose pattern compiles', () => { + expect(findCustomFieldIssues(field())).toStrictEqual({ label: false, pattern: false }); + }); + + it('should flag a label with no content in any language', () => { + expect(findCustomFieldIssues(field({ label: { en: ' ', fr: '' } })).label).toBe(true); + }); + + it('should flag a missing pattern', () => { + expect(findCustomFieldIssues(field({ pattern: '' })).pattern).toBe(true); + }); + + it('should flag a pattern that does not compile with the u flag, as the forms compile it', () => { + expect(findCustomFieldIssues(field({ pattern: '\\-' })).pattern).toBe(true); + }); +}); + +describe('isCustomFieldsLabelMissing', () => { + it('should flag a method label with no content in any language', () => { + expect(isCustomFieldsLabelMissing({ fields: [field()], label: { en: '' } })).toBe(true); + }); + + it('should accept a method label written in one language', () => { + expect(isCustomFieldsLabelMissing({ fields: [field()], label: { fr: 'Animal' } })).toBe(false); + }); +}); diff --git a/apps/web/src/utils/subject-identification-draft.ts b/apps/web/src/utils/subject-identification-draft.ts new file mode 100644 index 000000000..36d7dd165 --- /dev/null +++ b/apps/web/src/utils/subject-identification-draft.ts @@ -0,0 +1,83 @@ +import type { LocalizedString } from '@opendatacapture/schemas/core'; +import { + $CustomFieldsDefinitionData, + $CustomIdentificationField +} from '@opendatacapture/schemas/subject-identification'; +import type { + $UpdateSubjectIdentificationSettingsData, + CustomFieldsDefinitionData, + CustomIdentificationField, + SubjectIdentificationSettings +} from '@opendatacapture/schemas/subject-identification'; + +import { authoredLanguages, omitBlankLanguages } from './language'; + +/** A field being edited. Its `key` keeps the field's inputs with it when the fields are reordered. */ +type CustomFieldDraft = CustomIdentificationField & { key: string }; + +type CustomFieldsDraft = Omit & { fields: CustomFieldDraft[] }; + +/** + * Everything the Subject Identification tab saves with its one button. A section added to the tab + * adds its part here and to {@link toSubjectIdentificationDraft} and + * {@link toUpdateSubjectIdentificationSettingsData}. + */ +type SubjectIdentificationDraft = { + customFields: CustomFieldsDraft | null; +}; + +type CustomFieldIssues = { + label: boolean; + pattern: boolean; +}; + +const createCustomFieldDraft = (): CustomFieldDraft => ({ key: crypto.randomUUID(), label: {}, pattern: '' }); + +/** A definition has at least one field, so a new one starts with a field to fill in. */ +const createCustomFieldsDraft = (): CustomFieldsDraft => ({ fields: [createCustomFieldDraft()], label: {} }); + +const toSubjectIdentificationDraft = ({ customFields }: SubjectIdentificationSettings): SubjectIdentificationDraft => ({ + customFields: customFields && { + fields: customFields.fields.map((field) => ({ ...field, key: crypto.randomUUID() })), + label: customFields.label + } +}); + +const omitBlankOptionalText = (value: LocalizedString | null | undefined): LocalizedString | null => { + return authoredLanguages(value).length > 0 ? omitBlankLanguages(value) : null; +}; + +const toUpdateSubjectIdentificationSettingsData = ({ + customFields +}: SubjectIdentificationDraft): $UpdateSubjectIdentificationSettingsData => ({ + customFields: customFields && { + fields: customFields.fields.map(({ description, label, pattern, patternErrorMessage }) => ({ + description: omitBlankOptionalText(description), + label: omitBlankLanguages(label), + pattern, + patternErrorMessage: omitBlankOptionalText(patternErrorMessage) + })), + label: omitBlankLanguages(customFields.label) + } +}); + +// The schema decides what is invalid; the editor only decides where to say so. +const findCustomFieldIssues = ({ label, pattern }: CustomFieldDraft): CustomFieldIssues => ({ + label: !$CustomIdentificationField.shape.label.safeParse(label).success, + pattern: !$CustomIdentificationField.shape.pattern.safeParse(pattern).success +}); + +const isCustomFieldsLabelMissing = ({ label }: CustomFieldsDraft): boolean => { + return !$CustomFieldsDefinitionData.shape.label.safeParse(label).success; +}; + +export { + createCustomFieldDraft, + createCustomFieldsDraft, + findCustomFieldIssues, + isCustomFieldsLabelMissing, + toSubjectIdentificationDraft, + toUpdateSubjectIdentificationSettingsData +}; + +export type { CustomFieldDraft, CustomFieldIssues, CustomFieldsDraft, SubjectIdentificationDraft }; From b45ce85efbbd7e9de3bc9bd2c2cd520eb20f81b7 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 12:43:30 -0500 Subject: [PATCH 18/19] feat: choose which identification methods an instance offers The Subject Identification tab now lists the methods staff are offered, saved with the custom fields by the tab's one save. An instance that never chose offers Custom ID and Personal Info, as before; at least one method must be offered, and custom fields only once they are defined, so saving a definition does not offer it by itself. A method that is not offered disappears from Start Session, the data hub lookup and the group default-method select, and a form whose group prefers one falls back to the first offered. Saving the group's settings keeps that preference, unless a manager picks another method. Turning a method off changes no id, but the tab first says how many subjects it identifies, counted by the shape of their ids through GET /v1/subjects/identification/counts. The definition is locked only while one is stored: a cf_ id saved without a definition matches none, so it no longer makes every save of these settings fail. Closes #1546 Co-Authored-By: Claude Opus 5.5 --- .../docs/architecture/auth-and-permissions.md | 28 +-- apps/api/prisma/schema.prisma | 5 +- .../subject-identification.service.test.ts | 86 ++++++-- .../__tests__/subjects.controller.test.ts | 19 +- .../__tests__/subjects.service.test.ts | 27 +++ .../subject-identification.service.ts | 37 ++-- apps/api/src/subjects/subjects.controller.ts | 15 +- apps/api/src/subjects/subjects.service.ts | 44 +++- .../suites/11-subject-identification.suite.ts | 95 +++++++-- .../SubjectIdentificationTab.test.tsx | 3 +- .../IdentificationForm/IdentificationForm.tsx | 12 +- .../__tests__/IdentificationForm.test.tsx | 18 +- .../StartSessionForm/StartSessionForm.tsx | 16 +- .../__tests__/StartSessionForm.test.tsx | 12 +- .../CustomFieldsEditor.tsx | 8 +- .../OfferedMethodsSection.tsx | 77 +++++++ .../SubjectIdentificationSettingsForm.tsx | 195 ++++++++++++------ .../__tests__/CustomFieldsEditor.test.tsx | 1 + ...SubjectIdentificationSettingsForm.test.tsx | 113 +++++++++- .../useCustomIdentificationFields.test.ts | 18 +- ...seSubjectIdentificationCountsQuery.test.ts | 40 ++++ ...SubjectIdentificationMethodOptions.test.ts | 51 +++++ ...SubjectIdentificationSettingsQuery.test.ts | 3 +- ...jectIdentificationSettingsMutation.test.ts | 9 +- .../hooks/useCustomIdentificationFields.ts | 1 - .../useSubjectIdentificationCountsQuery.ts | 18 ++ .../useSubjectIdentificationMethodOptions.ts | 28 +++ .../_app/group/__tests__/manage.test.tsx | 37 +++- apps/web/src/routes/_app/group/manage.tsx | 39 ++-- .../session/__tests__/start-session.test.tsx | 17 +- .../src/routes/_app/session/start-session.tsx | 8 +- .../subject-identification-draft.test.ts | 29 ++- .../src/utils/subject-identification-draft.ts | 34 ++- .../4.2-hash-based-identification.md | 2 + .../__tests__/subject-identification.test.ts | 39 +++- .../subject-identification.ts | 52 ++++- packages/subject-utils/AGENTS.md | 6 +- packages/subject-utils/src/index.ts | 19 +- testing/src/pages/_app/admin/settings.page.ts | 2 +- testing/src/specs/custom-fields.spec.ts | 70 ++++++- 40 files changed, 1080 insertions(+), 253 deletions(-) create mode 100644 apps/web/src/components/SubjectIdentificationSettingsForm/OfferedMethodsSection.tsx create mode 100644 apps/web/src/hooks/__tests__/useSubjectIdentificationCountsQuery.test.ts create mode 100644 apps/web/src/hooks/__tests__/useSubjectIdentificationMethodOptions.test.ts create mode 100644 apps/web/src/hooks/useSubjectIdentificationCountsQuery.ts create mode 100644 apps/web/src/hooks/useSubjectIdentificationMethodOptions.ts diff --git a/.agents/docs/architecture/auth-and-permissions.md b/.agents/docs/architecture/auth-and-permissions.md index 321103650..e1f833697 100644 --- a/.agents/docs/architecture/auth-and-permissions.md +++ b/.agents/docs/architecture/auth-and-permissions.md @@ -19,16 +19,17 @@ that they may read _some_ subject; the `where` decides whether they may read _th one; the guard turns a missing one into a 500. Nothing checks the value. Routes whose declaration is not the ordinary `{ action, subject }` on the model they serve: -| Route | Declaration | Why it is safe | -| --------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `POST /v1/auth/login` | `'public'` | `@ThrottleLoginRequest()`; credentials checked in `AuthService.login`. | -| `GET /v1/setup` | `'public'` | Returns only `SetupState`. | -| `POST /v1/setup` | `'public'` | **`SetupService.initApp` drops the whole database.** It refuses only when `isSetup` is true and `NODE_ENV` is not `development`. | -| `DELETE /v1/setup` | `{ action: 'delete', subject: 'all' }` | Also refuses unless `NODE_ENV === 'test'`. | -| `GET /v1/gateway/healthcheck` | `[]` | Any login token. The module loads only when `GATEWAY_ENABLED`. | -| `POST /v1/instruments` | `{ action: 'manage', subject: 'Instrument' }` | No base level grants it, so admin-only in practice. The one `@AcceptsInstrumentToken()` route (below). | -| `PATCH /v1/users/self-update/:id` | `{ action: 'read', subject: 'User' }` | Deliberately weak; `UsersService.updateSelfById` refuses unless `id === currentUser.id`. | -| `GET /v1/summary` | five `read` rules | The only multi-element array; all five must pass. | +| Route | Declaration | Why it is safe | +| ------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST /v1/auth/login` | `'public'` | `@ThrottleLoginRequest()`; credentials checked in `AuthService.login`. | +| `GET /v1/setup` | `'public'` | Returns only `SetupState`. | +| `POST /v1/setup` | `'public'` | **`SetupService.initApp` drops the whole database.** It refuses only when `isSetup` is true and `NODE_ENV` is not `development`. | +| `DELETE /v1/setup` | `{ action: 'delete', subject: 'all' }` | Also refuses unless `NODE_ENV === 'test'`. | +| `GET /v1/gateway/healthcheck` | `[]` | Any login token. The module loads only when `GATEWAY_ENABLED`. | +| `POST /v1/instruments` | `{ action: 'manage', subject: 'Instrument' }` | No base level grants it, so admin-only in practice. The one `@AcceptsInstrumentToken()` route (below). | +| `PATCH /v1/users/self-update/:id` | `{ action: 'read', subject: 'User' }` | Deliberately weak; `UsersService.updateSelfById` refuses unless `id === currentUser.id`. | +| `GET /v1/summary` | five `read` rules | The only multi-element array; all five must pass. | +| `GET /v1/subjects/identification/settings` | `{ action: 'read', subject: 'Subject' }` | Serves the instance's `SetupState` definition of custom identifying fields, salt included, because the browser of anyone who identifies subjects derives their ids from it. Never on the public `GET /v1/setup`. | Adding a fourth `'public'` route or a second `[]` is a security decision: raise it rather than deciding alone. @@ -40,7 +41,7 @@ route, `POST /v1/groups` per #1468, and `PATCH /v1/groups/:id/archive` and `/una replaced a `DELETE /v1/groups/:id` that a group manager's `manage Group` reached; `$UpdateGroupData` omits `archivedAt`, so `PATCH /v1/groups/:id` cannot archive either), and where the data crosses groups with nothing to scope it by (audit logs, the instrument series overview, every repository's -sync log, mail settings). Most handlers carry their reason in a comment; +sync log, mail settings, the count of subjects by identification method). Most handlers carry their reason in a comment; `grep -rn 'RouteAccess(ADMIN_ONLY)' apps/api/src` lists them. `UsersService` refuses an admin archiving, disabling or demoting their own account, so the last admin cannot lock every `ADMIN_ONLY` route. @@ -53,7 +54,10 @@ reason, so a new call site that omits it compiles and reads every group's instru `StartSessionService` rolls back unscoped: when the record of a session instrument fails to save, it deletes the session it just created and, if `SubjectsService.exists` (a boolean, unscoped because a scoped lookup would miss a subject in another group) found no subject beforehand, the -subject too. `SessionsService.createMany` rolls back the same way. +subject too. `SessionsService.createMany` rolls back the same way. `SubjectsService.hasCustomFieldsSubjects` +(whether any id has the `cf_` prefix, which locks the instance-wide definition; only a boolean leaves +it) and `SubjectsService.countByIdentificationMethod` (every group's subjects, behind `ADMIN_ONLY`) +read across groups on purpose. ## Layer 2: row scoping diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index c568d757c..c22f408a4 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -541,8 +541,11 @@ type CustomFieldsDefinition { salt String } +// An empty list of offered methods is one an administrator never chose, which offers the built-in +// two; once chosen, at least one is offered. type SubjectIdentificationSettings { - customFields CustomFieldsDefinition? + customFields CustomFieldsDefinition? + offeredMethods SubjectIdentificationMethod[] } model SetupState { diff --git a/apps/api/src/subjects/__tests__/subject-identification.service.test.ts b/apps/api/src/subjects/__tests__/subject-identification.service.test.ts index f49e18cf0..a5a15b525 100644 --- a/apps/api/src/subjects/__tests__/subject-identification.service.test.ts +++ b/apps/api/src/subjects/__tests__/subject-identification.service.test.ts @@ -2,7 +2,7 @@ import type { Model } from '@douglasneuroinformatics/libnest'; import { getModelToken } from '@douglasneuroinformatics/libnest'; import { MockFactory } from '@douglasneuroinformatics/libnest/testing'; import type { MockedInstance } from '@douglasneuroinformatics/libnest/testing'; -import { ConflictException, InternalServerErrorException, ServiceUnavailableException } from '@nestjs/common'; +import { ConflictException, ServiceUnavailableException } from '@nestjs/common'; import { Test } from '@nestjs/testing'; import type { CustomFieldsDefinitionData } from '@opendatacapture/schemas/subject-identification'; import { beforeEach, describe, expect, it } from 'vitest'; @@ -19,6 +19,8 @@ const definitionData: CustomFieldsDefinitionData = { const storedDefinition = { ...definitionData, iterations: 1000, salt: 'ab'.repeat(32) }; +const BUILT_IN_METHODS: ['CUSTOM_ID', 'PERSONAL_INFO'] = ['CUSTOM_ID', 'PERSONAL_INFO']; + const setupState = (customFields: null | typeof storedDefinition = null) => ({ id: 'setup-1', isSetup: true, @@ -30,9 +32,9 @@ describe('SubjectIdentificationService', () => { let setupStateModel: MockedInstance>; let subjectsService: MockedInstance; - const savedCustomFields = () => { - return setupStateModel.update.mock.lastCall?.[0].data.subjectIdentificationSettings.set.customFields; - }; + const savedSettings = () => setupStateModel.update.mock.lastCall?.[0].data.subjectIdentificationSettings.set; + + const savedCustomFields = () => savedSettings().customFields; beforeEach(async () => { const moduleRef = await Test.createTestingModule({ @@ -51,7 +53,11 @@ describe('SubjectIdentificationService', () => { describe('getSettings', () => { it('should read an instance that never saved settings as having no definition', async () => { setupStateModel.findFirst.mockResolvedValueOnce({ subjectIdentificationSettings: null }); - await expect(service.getSettings()).resolves.toStrictEqual({ customFields: null, isCustomFieldsLocked: false }); + await expect(service.getSettings()).resolves.toStrictEqual({ + customFields: null, + isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] + }); }); it('should read an instance with no setup state as having no definition', async () => { @@ -59,6 +65,18 @@ describe('SubjectIdentificationService', () => { await expect(service.getSettings()).resolves.toMatchObject({ customFields: null }); }); + it('should offer the built-in methods until an administrator chooses which to offer', async () => { + setupStateModel.findFirst.mockResolvedValueOnce({ subjectIdentificationSettings: { offeredMethods: [] } }); + await expect(service.getSettings()).resolves.toMatchObject({ offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }); + }); + + it('should return the methods an administrator chose to offer', async () => { + setupStateModel.findFirst.mockResolvedValueOnce({ + subjectIdentificationSettings: { offeredMethods: ['CUSTOM_FIELDS'] } + }); + await expect(service.getSettings()).resolves.toMatchObject({ offeredMethods: ['CUSTOM_FIELDS'] }); + }); + it('should return the stored definition, salt included, since the browser derives ids from it', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); await expect(service.getSettings()).resolves.toMatchObject({ customFields: storedDefinition }); @@ -69,19 +87,25 @@ describe('SubjectIdentificationService', () => { subjectsService.hasCustomFieldsSubjects.mockResolvedValueOnce(true); await expect(service.getSettings()).resolves.toMatchObject({ isCustomFieldsLocked: true }); }); + + it('should report nothing locked while no definition is stored, whatever ids subjects carry', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState()); + subjectsService.hasCustomFieldsSubjects.mockResolvedValue(true); + await expect(service.getSettings()).resolves.toMatchObject({ isCustomFieldsLocked: false }); + }); }); describe('updateSettings', () => { it('should refuse to save before the instance is set up', async () => { setupStateModel.findFirst.mockResolvedValueOnce({ isSetup: false }); - await expect(service.updateSettings({ customFields: definitionData })).rejects.toBeInstanceOf( - ServiceUnavailableException - ); + await expect( + service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }) + ).rejects.toBeInstanceOf(ServiceUnavailableException); }); it('should give a first definition a random 32-byte salt and 600,000 iterations', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState()); - await service.updateSettings({ customFields: definitionData }); + await service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }); expect(savedCustomFields()).toStrictEqual({ ...definitionData, iterations: 600_000, @@ -91,15 +115,24 @@ describe('SubjectIdentificationService', () => { it('should give two instances different salts, so their ids are not comparable', async () => { setupStateModel.findFirst.mockResolvedValue(setupState()); - await service.updateSettings({ customFields: definitionData }); + await service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }); const first = savedCustomFields().salt; - await service.updateSettings({ customFields: definitionData }); + await service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }); expect(savedCustomFields().salt).not.toBe(first); }); + it('should store the offered methods in one fixed order, whatever order they were sent in', async () => { + setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); + await service.updateSettings({ customFields: definitionData, offeredMethods: ['CUSTOM_FIELDS', 'CUSTOM_ID'] }); + expect(savedSettings().offeredMethods).toStrictEqual(['CUSTOM_ID', 'CUSTOM_FIELDS']); + }); + it('should keep the stored salt and iteration count when the definition is saved again', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); - await service.updateSettings({ customFields: { ...definitionData, label: { en: 'Mouse information' } } }); + await service.updateSettings({ + customFields: { ...definitionData, label: { en: 'Mouse information' } }, + offeredMethods: BUILT_IN_METHODS + }); expect(savedCustomFields()).toMatchObject({ iterations: 1000, label: { en: 'Mouse information' }, @@ -109,13 +142,16 @@ describe('SubjectIdentificationService', () => { it('should remove the definition while no subject has been identified with it', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); - await service.updateSettings({ customFields: null }); + await service.updateSettings({ customFields: null, offeredMethods: BUILT_IN_METHODS }); expect(savedCustomFields()).toBeNull(); }); it('should let the fields be added to or removed while no subject has been identified with them', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); - await service.updateSettings({ customFields: { ...definitionData, fields: [field('Animal ID')] } }); + await service.updateSettings({ + customFields: { ...definitionData, fields: [field('Animal ID')] }, + offeredMethods: BUILT_IN_METHODS + }); expect(savedCustomFields().fields).toHaveLength(1); }); @@ -126,14 +162,19 @@ describe('SubjectIdentificationService', () => { it('should refuse to remove the definition', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); - await expect(service.updateSettings({ customFields: null })).rejects.toBeInstanceOf(ConflictException); + await expect( + service.updateSettings({ customFields: null, offeredMethods: BUILT_IN_METHODS }) + ).rejects.toBeInstanceOf(ConflictException); expect(setupStateModel.update).not.toHaveBeenCalled(); }); it('should refuse to change the number of fields', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState(storedDefinition)); await expect( - service.updateSettings({ customFields: { ...definitionData, fields: [field('Animal ID')] } }) + service.updateSettings({ + customFields: { ...definitionData, fields: [field('Animal ID')] }, + offeredMethods: BUILT_IN_METHODS + }) ).rejects.toBeInstanceOf(ConflictException); expect(setupStateModel.update).not.toHaveBeenCalled(); }); @@ -147,21 +188,22 @@ describe('SubjectIdentificationService', () => { ], label: { en: 'Mouse' } }; - await service.updateSettings({ customFields: corrected }); + await service.updateSettings({ customFields: corrected, offeredMethods: BUILT_IN_METHODS }); expect(savedCustomFields()).toStrictEqual({ ...corrected, iterations: 1000, salt: 'ab'.repeat(32) }); }); - it('should fail loudly when subjects were identified with fields that are no longer stored', async () => { + it('should save a first definition despite a cf_ subject no stored definition derived, since that id has none to keep', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState()); - await expect(service.updateSettings({ customFields: definitionData })).rejects.toBeInstanceOf( - InternalServerErrorException - ); + await service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }); + expect(savedCustomFields()).toMatchObject(definitionData); }); }); it('should return the settings as they now stand', async () => { setupStateModel.findFirst.mockResolvedValueOnce(setupState()).mockResolvedValueOnce(setupState(storedDefinition)); - await expect(service.updateSettings({ customFields: definitionData })).resolves.toMatchObject({ + await expect( + service.updateSettings({ customFields: definitionData, offeredMethods: BUILT_IN_METHODS }) + ).resolves.toMatchObject({ customFields: storedDefinition }); }); diff --git a/apps/api/src/subjects/__tests__/subjects.controller.test.ts b/apps/api/src/subjects/__tests__/subjects.controller.test.ts index 0bcc9b0f8..c5cf5f851 100644 --- a/apps/api/src/subjects/__tests__/subjects.controller.test.ts +++ b/apps/api/src/subjects/__tests__/subjects.controller.test.ts @@ -39,17 +39,28 @@ describe('SubjectsController', () => { subjectsService = moduleRef.get(SubjectsService); }); + it('should count the subjects of each identification method', async () => { + const counts = { CUSTOM_FIELDS: 1, CUSTOM_ID: 2, PERSONAL_INFO: 3 }; + subjectsService.countByIdentificationMethod.mockResolvedValueOnce(counts); + await expect(subjectsController.countByIdentificationMethod()).resolves.toBe(counts); + }); + it('should return the subject identification settings', async () => { - const settings = { customFields: null, isCustomFieldsLocked: false }; + const settings = { customFields: null, isCustomFieldsLocked: false, offeredMethods: ['CUSTOM_ID' as const] }; subjectIdentificationService.getSettings.mockResolvedValueOnce(settings); await expect(subjectsController.getIdentificationSettings()).resolves.toBe(settings); }); it('should update the subject identification settings', async () => { - const settings = { customFields: null, isCustomFieldsLocked: false }; + const settings = { customFields: null, isCustomFieldsLocked: false, offeredMethods: ['CUSTOM_ID' as const] }; subjectIdentificationService.updateSettings.mockResolvedValueOnce(settings); - await expect(subjectsController.updateIdentificationSettings({ customFields: null })).resolves.toBe(settings); - expect(subjectIdentificationService.updateSettings).toHaveBeenCalledWith({ customFields: null }); + await expect( + subjectsController.updateIdentificationSettings({ customFields: null, offeredMethods: ['CUSTOM_ID'] }) + ).resolves.toBe(settings); + expect(subjectIdentificationService.updateSettings).toHaveBeenCalledWith({ + customFields: null, + offeredMethods: ['CUSTOM_ID'] + }); }); it('should delete a subject within what the caller may delete, forcing when asked', async () => { diff --git a/apps/api/src/subjects/__tests__/subjects.service.test.ts b/apps/api/src/subjects/__tests__/subjects.service.test.ts index 10631b73e..dddf2a7d5 100644 --- a/apps/api/src/subjects/__tests__/subjects.service.test.ts +++ b/apps/api/src/subjects/__tests__/subjects.service.test.ts @@ -469,6 +469,33 @@ describe('SubjectsService', () => { }); }); + describe('countByIdentificationMethod', () => { + it('should count every method, reporting zero for one no subject uses', async () => { + subjectModel.aggregateRaw.mockResolvedValueOnce([ + { _id: 'CUSTOM_ID', count: 4 }, + { _id: 'PERSONAL_INFO', count: 2 } + ]); + await expect(subjectsService.countByIdentificationMethod()).resolves.toStrictEqual({ + CUSTOM_FIELDS: 0, + CUSTOM_ID: 4, + PERSONAL_INFO: 2 + }); + }); + + it('should tell the methods apart by the shape of the id, checking a custom-fields id before a name hash', async () => { + subjectModel.aggregateRaw.mockResolvedValueOnce([]); + await subjectsService.countByIdentificationMethod(); + const [{ pipeline }] = subjectModel.aggregateRaw.mock.lastCall as [{ pipeline: any[] }]; + expect(pipeline[0].$group._id.$switch).toStrictEqual({ + branches: [ + { case: { $regexMatch: { input: '$_id', regex: '^cf_[0-9a-f]{64}$' } }, then: 'CUSTOM_FIELDS' }, + { case: { $regexMatch: { input: '$_id', regex: '^[0-9a-f]{64}$' } }, then: 'PERSONAL_INFO' } + ], + default: 'CUSTOM_ID' + }); + }); + }); + describe('hasCustomFieldsSubjects', () => { // A custom-fields subject stores no name, so only its id tells it apart from a custom id. it('should look for any subject whose id carries the custom-fields prefix, by a lexical range', async () => { diff --git a/apps/api/src/subjects/subject-identification.service.ts b/apps/api/src/subjects/subject-identification.service.ts index 29aff76a6..80402dcbc 100644 --- a/apps/api/src/subjects/subject-identification.service.ts +++ b/apps/api/src/subjects/subject-identification.service.ts @@ -2,12 +2,9 @@ import { randomBytes } from 'node:crypto'; import { InjectModel } from '@douglasneuroinformatics/libnest'; import type { Model } from '@douglasneuroinformatics/libnest'; -import { - ConflictException, - Injectable, - InternalServerErrorException, - ServiceUnavailableException -} from '@nestjs/common'; +import { ConflictException, Injectable, ServiceUnavailableException } from '@nestjs/common'; +import { $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import { DEFAULT_OFFERED_SUBJECT_IDENTIFICATION_METHODS } from '@opendatacapture/schemas/subject-identification'; import type { $UpdateSubjectIdentificationSettingsData, SubjectIdentificationSettings @@ -32,14 +29,21 @@ export class SubjectIdentificationService { async getSettings(): Promise { const setupState = await this.setupStateModel.findFirst({ select: { subjectIdentificationSettings: true } }); + const [firstOfferedMethod, ...otherOfferedMethods] = + setupState?.subjectIdentificationSettings?.offeredMethods ?? []; + const customFields = setupState?.subjectIdentificationSettings?.customFields ?? null; return { - customFields: setupState?.subjectIdentificationSettings?.customFields ?? null, - isCustomFieldsLocked: await this.subjectsService.hasCustomFieldsSubjects() + customFields, + isCustomFieldsLocked: customFields !== null && (await this.subjectsService.hasCustomFieldsSubjects()), + offeredMethods: firstOfferedMethod + ? [firstOfferedMethod, ...otherOfferedMethods] + : DEFAULT_OFFERED_SUBJECT_IDENTIFICATION_METHODS }; } async updateSettings({ - customFields + customFields, + offeredMethods }: $UpdateSubjectIdentificationSettingsData): Promise { const setupState = await this.setupStateModel.findFirst(); if (!setupState?.isSetup) { @@ -47,13 +51,10 @@ export class SubjectIdentificationService { } const stored = setupState.subjectIdentificationSettings?.customFields ?? null; // The values typed into the fields are never stored, so once an id has been derived from them, a - // different salt, iteration count or list of fields could never produce that id again. - if (await this.subjectsService.hasCustomFieldsSubjects()) { - if (!stored) { - throw new InternalServerErrorException( - 'Subjects are identified by custom fields, but no definition of the fields is stored' - ); - } else if (!customFields) { + // different salt, iteration count or list of fields could never produce that id again. A `cf_` id + // with no definition stored (one uploaded, say) matches no definition, so there is none to protect. + if (stored && (await this.subjectsService.hasCustomFieldsSubjects())) { + if (!customFields) { throw new ConflictException( 'The custom identifying fields cannot be removed once a subject has been identified with them' ); @@ -71,7 +72,9 @@ export class SubjectIdentificationService { ...customFields, iterations: stored?.iterations ?? CUSTOM_FIELDS_ITERATIONS, salt: stored?.salt ?? randomBytes(CUSTOM_FIELDS_SALT_BYTES).toString('hex') - } + }, + // Stored in one fixed order, so the first offered method a form falls back to is predictable. + offeredMethods: $SubjectIdentificationMethod.options.filter((method) => offeredMethods.includes(method)) } } }, diff --git a/apps/api/src/subjects/subjects.controller.ts b/apps/api/src/subjects/subjects.controller.ts index 95dff7a65..353a77a92 100644 --- a/apps/api/src/subjects/subjects.controller.ts +++ b/apps/api/src/subjects/subjects.controller.ts @@ -2,7 +2,10 @@ import { $BooleanLike } from '@douglasneuroinformatics/libjs'; import { ApiOperation, CurrentUser, ParseSchemaPipe, ValidObjectIdPipe } from '@douglasneuroinformatics/libnest'; import { Body, Controller, Delete, Get, Param, Put, Query } from '@nestjs/common'; import { $UpdateSubjectIdentificationSettingsData } from '@opendatacapture/schemas/subject-identification'; -import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import type { + SubjectIdentificationCounts, + SubjectIdentificationSettings +} from '@opendatacapture/schemas/subject-identification'; import z from 'zod/v4'; import type { AppAbility } from '@/auth/auth.types'; @@ -18,6 +21,16 @@ export class SubjectsController { private readonly subjectsService: SubjectsService ) {} + @ApiOperation({ + description: 'How many subjects each identification method identifies, read from the shape of their ids.', + summary: 'Count Subjects by Identification Method' + }) + @Get('identification/counts') + @RouteAccess(ADMIN_ONLY) + countByIdentificationMethod(): Promise { + return this.subjectsService.countByIdentificationMethod(); + } + @ApiOperation({ summary: 'Delete Subject' }) @Delete(':id') @RouteAccess({ action: 'delete', subject: 'Subject' }) diff --git a/apps/api/src/subjects/subjects.service.ts b/apps/api/src/subjects/subjects.service.ts index 835b84bed..a6c19fbe0 100644 --- a/apps/api/src/subjects/subjects.service.ts +++ b/apps/api/src/subjects/subjects.service.ts @@ -2,9 +2,15 @@ import { InjectModel, InjectPrismaClient, LoggingService } from '@douglasneuroin import type { Model } from '@douglasneuroinformatics/libnest'; import { ConflictException, Injectable, NotFoundException } from '@nestjs/common'; import { DEFAULT_GROUP_NAME } from '@opendatacapture/schemas/core'; -import { $CreateSubjectData } from '@opendatacapture/schemas/subject'; -import { CUSTOM_FIELDS_SUBJECT_ID_PREFIX, encodeScopedSubjectId } from '@opendatacapture/subject-utils'; +import { $CreateSubjectData, $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import type { SubjectIdentificationCounts } from '@opendatacapture/schemas/subject-identification'; +import { + CUSTOM_FIELDS_SUBJECT_ID_PREFIX, + DERIVED_SUBJECT_ID_PATTERNS, + encodeScopedSubjectId +} from '@opendatacapture/subject-utils'; import type { Prisma } from '@prisma/client'; +import { z } from 'zod/v4'; import { accessibleQuery } from '@/auth/ability.utils'; import type { AppAbility } from '@/auth/auth.types'; @@ -67,6 +73,40 @@ export class SubjectsService { }); } + /** + * How many subjects in the instance, in any group, each method identifies, read from the shape of + * their ids: a custom-fields subject stores no name, and a custom-id one may store every field a + * name hash is made from, so nothing but the id tells the three apart. Unscoped, for the + * administrator turning a method off for everyone. + */ + async countByIdentificationMethod(): Promise { + const rows = await this.subjectModel.aggregateRaw({ + pipeline: [ + { + $group: { + _id: { + $switch: { + branches: Object.entries(DERIVED_SUBJECT_ID_PATTERNS).map(([method, pattern]) => ({ + case: { $regexMatch: { input: '$_id', regex: pattern.source } }, + then: method + })), + default: 'CUSTOM_ID' + } + }, + count: { $sum: 1 } + } + } + ] + }); + const counts = z.array(z.object({ _id: $SubjectIdentificationMethod, count: z.number() })).parse(rows); + return { + CUSTOM_FIELDS: 0, + CUSTOM_ID: 0, + PERSONAL_INFO: 0, + ...Object.fromEntries(counts.map(({ _id, count }) => [_id, count])) + }; + } + async create({ id, ...data diff --git a/apps/api/test/suites/11-subject-identification.suite.ts b/apps/api/test/suites/11-subject-identification.suite.ts index 7596f19d2..ad80fd7d1 100644 --- a/apps/api/test/suites/11-subject-identification.suite.ts +++ b/apps/api/test/suites/11-subject-identification.suite.ts @@ -1,5 +1,6 @@ -import { randomUUID } from 'node:crypto'; +import { randomBytes, randomUUID } from 'node:crypto'; +import { $SubjectIdentificationCounts } from '@opendatacapture/schemas/subject-identification'; import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; import { beforeAll, describe, expect, it } from 'vitest'; @@ -12,6 +13,8 @@ const PASSWORD = 'DataCapture2025_Test'; // Its own address, so these logins never count against another suite's throttling budget. const LOGIN_ADDRESS = '192.0.2.111'; +const BUILT_IN_METHODS = ['CUSTOM_ID', 'PERSONAL_INFO']; + const definition = { fields: [ { label: { en: 'Animal ID' }, pattern: '[A-Z]{2}[0-9]+' }, @@ -46,6 +49,18 @@ export default defineSuite('subject identification', function () { return this.app.inject({ headers, method: 'PUT', payload, url: '/v1/subjects/identification/settings' }); }; + const startSession = async (subjectId: string) => { + const response = await this.app.inject({ + headers: standardHeaders, + method: 'POST', + payload: { date: new Date(), groupId, subjectData: { id: subjectId }, type: 'IN_PERSON' }, + url: '/v1/sessions' + }); + expect(response.statusCode).toBe(201); + }; + + const hexDigest = () => randomBytes(32).toString('hex'); + beforeAll(async () => { adminHeaders = await login('admin'); const group = await this.app.inject({ @@ -78,18 +93,21 @@ export default defineSuite('subject identification', function () { it('should report no definition, unlocked', async () => { await expect(getSettings(adminHeaders)).resolves.toStrictEqual({ customFields: null, - isCustomFieldsLocked: false + isCustomFieldsLocked: false, + offeredMethods: BUILT_IN_METHODS }); }); }); describe('PUT /v1/subjects/identification/settings', () => { it('should refuse anyone but an administrator', async () => { - expect((await putSettings(standardHeaders, { customFields: definition })).statusCode).toBe(403); + expect( + (await putSettings(standardHeaders, { customFields: definition, offeredMethods: BUILT_IN_METHODS })).statusCode + ).toBe(403); }); it('should store the definition with a salt and iteration count of the server’s choosing', async () => { - const response = await putSettings(adminHeaders, { customFields: definition }); + const response = await putSettings(adminHeaders, { customFields: definition, offeredMethods: BUILT_IN_METHODS }); expect(response.statusCode).toBe(200); const { customFields } = response.json(); expect(customFields).toMatchObject({ ...definition, iterations: 600_000 }); @@ -97,6 +115,52 @@ export default defineSuite('subject identification', function () { }); }); + describe('offered methods', () => { + it('should refuse to offer custom fields that are not defined', async () => { + const response = await putSettings(adminHeaders, { + customFields: null, + offeredMethods: ['CUSTOM_ID', 'CUSTOM_FIELDS'] + }); + expect(response.statusCode).toBe(400); + }); + + it('should offer custom fields once they are defined and ticked', async () => { + const response = await putSettings(adminHeaders, { + customFields: definition, + offeredMethods: ['CUSTOM_FIELDS', 'CUSTOM_ID', 'PERSONAL_INFO'] + }); + expect(response.json().offeredMethods).toStrictEqual([ + 'CUSTOM_ID', + 'PERSONAL_INFO', + 'CUSTOM_FIELDS' + ]); + }); + }); + + describe('GET /v1/subjects/identification/counts', () => { + const getCounts = (headers: AuthHeaders) => { + return this.app.inject({ headers, method: 'GET', url: '/v1/subjects/identification/counts' }); + }; + + it('should refuse anyone but an administrator', async () => { + expect((await getCounts(standardHeaders)).statusCode).toBe(403); + }); + + // Every suite shares the database, so the counts are compared before and after rather than exactly. + it('should count each subject under the method the shape of its id names', async () => { + const before = $SubjectIdentificationCounts.parse((await getCounts(adminHeaders)).json()); + await startSession(hexDigest()); + await startSession(`Identification$${randomUUID()}`); + await startSession(`cf_${hexDigest()}`); + const after = $SubjectIdentificationCounts.parse((await getCounts(adminHeaders)).json()); + expect(after).toStrictEqual({ + CUSTOM_FIELDS: before.CUSTOM_FIELDS + 1, + CUSTOM_ID: before.CUSTOM_ID + 1, + PERSONAL_INFO: before.PERSONAL_INFO + 1 + }); + }); + }); + describe('GET /v1/subjects/identification/settings', () => { it('should serve the definition, salt included, to a user who only reads subjects', async () => { const settings = await getSettings(standardHeaders); @@ -115,18 +179,7 @@ export default defineSuite('subject identification', function () { beforeAll(async () => { salt = (await getSettings(adminHeaders)).customFields!.salt; - const session = await this.app.inject({ - headers: standardHeaders, - method: 'POST', - payload: { - date: new Date(), - groupId, - subjectData: { id: `cf_${'0'.repeat(64)}` }, - type: 'IN_PERSON' - }, - url: '/v1/sessions' - }); - expect(session.statusCode).toBe(201); + await startSession(`cf_${'0'.repeat(64)}`); }); it('should report the definition locked', async () => { @@ -134,12 +187,16 @@ export default defineSuite('subject identification', function () { }); it('should refuse to remove the definition', async () => { - expect((await putSettings(adminHeaders, { customFields: null })).statusCode).toBe(409); + expect( + (await putSettings(adminHeaders, { customFields: null, offeredMethods: BUILT_IN_METHODS })).statusCode + ).toBe(409); }); it('should refuse to change the number of fields', async () => { const fewer = { ...definition, fields: definition.fields.slice(0, 1) }; - expect((await putSettings(adminHeaders, { customFields: fewer })).statusCode).toBe(409); + expect( + (await putSettings(adminHeaders, { customFields: fewer, offeredMethods: BUILT_IN_METHODS })).statusCode + ).toBe(409); }); it('should still accept corrected labels and patterns, keeping the salt', async () => { @@ -147,7 +204,7 @@ export default defineSuite('subject identification', function () { fields: definition.fields.map((field) => ({ ...field, pattern: '[A-Z0-9]+' })), label: { en: 'Mouse information' } }; - const response = await putSettings(adminHeaders, { customFields: corrected }); + const response = await putSettings(adminHeaders, { customFields: corrected, offeredMethods: BUILT_IN_METHODS }); expect(response.statusCode).toBe(200); expect(response.json().customFields).toMatchObject({ ...corrected, salt }); }); diff --git a/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx b/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx index 575d7a8c1..9a6f584cc 100644 --- a/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx +++ b/apps/web/src/components/ApplicationSettings/__tests__/SubjectIdentificationTab.test.tsx @@ -15,7 +15,8 @@ const SETTINGS: SubjectIdentificationSettings = { label: { en: 'Animal information' }, salt: 'ab'.repeat(32) }, - isCustomFieldsLocked: true + isCustomFieldsLocked: true, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }; const mocks = vi.hoisted(() => ({ diff --git a/apps/web/src/components/IdentificationForm/IdentificationForm.tsx b/apps/web/src/components/IdentificationForm/IdentificationForm.tsx index f86402ad7..25b46cd4b 100644 --- a/apps/web/src/components/IdentificationForm/IdentificationForm.tsx +++ b/apps/web/src/components/IdentificationForm/IdentificationForm.tsx @@ -8,6 +8,7 @@ import type { Promisable } from 'type-fest'; import { z } from 'zod/v4'; import { useCustomIdentificationFields } from '@/hooks/useCustomIdentificationFields'; +import { useSubjectIdentificationMethodOptions } from '@/hooks/useSubjectIdentificationMethodOptions'; import { useSubjectIdentificationSettingsQuery } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useAppStore } from '@/store'; @@ -20,12 +21,9 @@ export const IdentificationForm = ({ onSubmit }: IdentificationFormProps) => { const { t } = useTranslation(); const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); const customFields = useCustomIdentificationFields(subjectIdentificationSettingsQuery.data.customFields); - - const methodOptions: { [method: string]: string } = { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo'), - ...(customFields.label === null ? {} : { CUSTOM_FIELDS: customFields.label }) - }; + const { options: methodOptions, preferMethod } = useSubjectIdentificationMethodOptions( + subjectIdentificationSettingsQuery.data + ); return ( { ]} data-testid="identification-form" initialValues={{ - subjectIdentificationMethod: currentGroup?.settings.defaultIdentificationMethod ?? 'PERSONAL_INFO' + subjectIdentificationMethod: preferMethod(currentGroup?.settings.defaultIdentificationMethod ?? 'PERSONAL_INFO') }} submitBtnLabel={t('core.submit')} validationSchema={z diff --git a/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx b/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx index 2ddc6dd1d..fe66a352e 100644 --- a/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx +++ b/apps/web/src/components/IdentificationForm/__tests__/IdentificationForm.test.tsx @@ -18,12 +18,15 @@ const store = vi.hoisted(() => { const subjectUtils = vi.hoisted(() => ({ generateSubjectHash: vi.fn() })); const settings = vi.hoisted(() => { - const state: { customFields: CustomFieldsDefinition | null } = { customFields: null }; + const state: { customFields: CustomFieldsDefinition | null; offeredMethods: [string, ...string[]] } = { + customFields: null, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] + }; return state; }); vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', () => ({ - useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: settings.customFields } }) + useSubjectIdentificationSettingsQuery: () => ({ data: settings }) })); vi.mock('@/store', () => ({ @@ -83,6 +86,7 @@ describe('IdentificationForm', () => { i18n.changeLanguage('en'); store.currentGroup = null; settings.customFields = null; + settings.offeredMethods = ['CUSTOM_ID', 'PERSONAL_INFO']; subjectUtils.generateSubjectHash.mockResolvedValue('subject-hash'); }); @@ -160,6 +164,15 @@ describe('IdentificationForm', () => { }); }); + // The instance may stop offering the method a group prefers; the lookup still has to open on one. + it("should open on the first offered method when the group's preferred one is not offered", () => { + settings.offeredMethods = ['CUSTOM_ID']; + store.currentGroup = createGroup('PERSONAL_INFO'); + renderForm(); + expect(field('id')).toBeTruthy(); + expect(field('firstName')).toBeNull(); + }); + describe('with custom fields', () => { beforeEach(() => { settings.customFields = { @@ -168,6 +181,7 @@ describe('IdentificationForm', () => { label: { en: 'Animal information' }, salt: '0f'.repeat(32) }; + settings.offeredMethods = ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS']; store.currentGroup = createGroup('CUSTOM_FIELDS'); }); diff --git a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx index 05f3015a0..beae5d283 100644 --- a/apps/web/src/components/StartSessionForm/StartSessionForm.tsx +++ b/apps/web/src/components/StartSessionForm/StartSessionForm.tsx @@ -11,7 +11,7 @@ import type { Group } from '@opendatacapture/schemas/group'; import { $SessionType } from '@opendatacapture/schemas/session'; import type { $CreateSessionData } from '@opendatacapture/schemas/session'; import type { Sex } from '@opendatacapture/schemas/subject'; -import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; import { encodeScopedSubjectId, generateSubjectHash } from '@opendatacapture/subject-utils'; import type { Promisable } from 'type-fest'; import { z } from 'zod/v4'; @@ -19,6 +19,7 @@ import { z } from 'zod/v4'; import { useCustomIdentificationFields } from '@/hooks/useCustomIdentificationFields'; import type { CustomFieldsFormData } from '@/hooks/useCustomIdentificationFields'; import { useSubjectDemographicsLookup } from '@/hooks/useSubjectDemographicsLookup'; +import { useSubjectIdentificationMethodOptions } from '@/hooks/useSubjectIdentificationMethodOptions'; import { getValueForLanguage } from '@/utils/language'; const MILLISECONDS_PER_YEAR = 31556952000; @@ -41,18 +42,18 @@ type StartSessionFormData = CustomFieldsFormData & { type StartSessionFormProps = { currentGroup: Group | null; - customFieldsDefinition: CustomFieldsDefinition | null; customSubjectIds: string[]; initialValues?: FormTypes.PartialNullableData; onSubmit: (data: $CreateSessionData) => Promisable; readOnly: boolean; + subjectIdentificationSettings: Pick; username?: null | string; }; export const StartSessionForm = ({ currentGroup, - customFieldsDefinition, customSubjectIds, + subjectIdentificationSettings, username, initialValues, readOnly, @@ -62,13 +63,8 @@ export const StartSessionForm = ({ const lookupDemographics = useSubjectDemographicsLookup(); const [autofilled, setAutofilled] = useState({}); const latestIdentity = useRef(''); - const customFields = useCustomIdentificationFields(customFieldsDefinition); - - const methodOptions: { [method: string]: string } = { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo'), - ...(customFields.label === null ? {} : { CUSTOM_FIELDS: customFields.label }) - }; + const customFields = useCustomIdentificationFields(subjectIdentificationSettings.customFields); + const { options: methodOptions } = useSubjectIdentificationMethodOptions(subjectIdentificationSettings); const scopeCustomId = (customId: string) => { return encodeScopedSubjectId(customId, { groupName: currentGroup?.name ?? DEFAULT_GROUP_NAME }); diff --git a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx index 1ab99513d..14c719e3d 100644 --- a/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx +++ b/apps/web/src/components/StartSessionForm/__tests__/StartSessionForm.test.tsx @@ -56,9 +56,12 @@ const renderForm = ( @@ -335,9 +338,9 @@ describe('StartSessionForm', () => { @@ -451,8 +454,9 @@ describe('StartSessionForm', () => { }); describe('with custom fields', () => { - const renderWithCustomFields = () => - renderForm([], null, 'CUSTOM_FIELDS', createQueryClient(), customFieldsDefinition); + const renderWithCustomFields = () => { + return renderForm([], null, 'CUSTOM_FIELDS', createQueryClient(), customFieldsDefinition); + }; const fillCustomFields = (form: HTMLElement, values: [string, string]) => { values.forEach((value, index) => { diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx index ec6f63ace..8b8ca7d23 100644 --- a/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/CustomFieldsEditor.tsx @@ -234,6 +234,7 @@ export type CustomFieldsEditorProps = { onChange: (value: CustomFieldsDraft | null) => void; /** Shows every missing entry as an error, once a save has been refused for one. */ showErrors: boolean; + title: string; value: CustomFieldsDraft | null; }; @@ -244,17 +245,14 @@ export const CustomFieldsEditor = ({ isLocked, onChange, showErrors, + title, value }: CustomFieldsEditorProps) => { const { t } = useTranslation(); return ( - {t({ - en: 'Custom Identifying Fields', - es: 'Campos de identificación personalizados', - fr: "Champs d'identification personnalisés" - })} + {title}

{t({ diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/OfferedMethodsSection.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/OfferedMethodsSection.tsx new file mode 100644 index 000000000..eeb7209cf --- /dev/null +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/OfferedMethodsSection.tsx @@ -0,0 +1,77 @@ +import { Checkbox, Heading, Label } from '@douglasneuroinformatics/libui/components'; +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import { $SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; + +import { getValueForLanguage } from '@/utils/language'; +import { sortByLabel } from '@/utils/sort-by-label'; +import type { CustomFieldsDraft } from '@/utils/subject-identification-draft'; + +type OfferedMethodsSectionProps = { + customFields: CustomFieldsDraft | null; + onChange: (offeredMethods: SubjectIdentificationMethod[]) => void; + showErrors: boolean; + title: string; + value: SubjectIdentificationMethod[]; +}; + +export const OfferedMethodsSection = ({ + customFields, + onChange, + showErrors, + title, + value +}: OfferedMethodsSectionProps) => { + const { resolvedLanguage, t } = useTranslation(); + const labels: { [K in SubjectIdentificationMethod]: string } = { + CUSTOM_FIELDS: + (customFields && getValueForLanguage(customFields.label, resolvedLanguage)) ?? + t({ en: 'Custom fields', es: 'Campos personalizados', fr: 'Champs personnalisés' }), + CUSTOM_ID: t('common.customIdentifier'), + PERSONAL_INFO: t('common.personalInfo') + }; + + const toggle = (method: SubjectIdentificationMethod) => { + onChange(value.includes(method) ? value.filter((offered) => offered !== method) : [...value, method]); + }; + + return ( +

+ {title} +

+ {t({ + en: 'The methods staff can identify subjects by in Start Session, the data hub lookup and a group’s default method. Changing them changes no subject’s id, so it can be undone.', + es: 'Los métodos con los que el personal puede identificar a los sujetos al iniciar una sesión, en la búsqueda del centro de datos y como método predeterminado de un grupo. Cambiarlos no modifica el identificador de ningún sujeto, por lo que se puede deshacer.', + fr: "Les méthodes par lesquelles le personnel peut identifier les sujets au démarrage d'une session, dans la recherche du centre de données et comme méthode par défaut d'un groupe. Les modifier ne change l'identifiant d'aucun sujet ; c'est donc réversible." + })} +

+ {sortByLabel($SubjectIdentificationMethod.options.map((method) => ({ label: labels[method], method }))).map( + ({ label, method }) => { + // Custom fields can be offered only once they are defined; the definition is saved with this. + const isUnavailable = method === 'CUSTOM_FIELDS' && customFields === null; + return ( +
+ toggle(method)} + /> + +
+ ); + } + )} + {showErrors && value.length === 0 && ( +

+ {t({ + en: 'Offer at least one method.', + es: 'Ofrezca al menos un método.', + fr: 'Proposez au moins une méthode.' + })} +

+ )} +
+ ); +}; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx index 69a230b74..3203609dc 100644 --- a/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/SubjectIdentificationSettingsForm.tsx @@ -1,16 +1,20 @@ -import { useState } from 'react'; +import React, { useState } from 'react'; import { Button, Dialog } from '@douglasneuroinformatics/libui/components'; import { useNotificationsStore, useTranslation } from '@douglasneuroinformatics/libui/hooks'; import type { Language } from '@opendatacapture/schemas/core'; +import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; import { $UpdateSubjectIdentificationSettingsData } from '@opendatacapture/schemas/subject-identification'; import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; import { useQueryClient } from '@tanstack/react-query'; import { isAxiosError } from 'axios'; import { Loader2Icon } from 'lucide-react'; +import { useSubjectIdentificationCountsQuery } from '@/hooks/useSubjectIdentificationCountsQuery'; +import { useSubjectIdentificationMethodOptions } from '@/hooks/useSubjectIdentificationMethodOptions'; import { subjectIdentificationSettingsQueryOptions } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useUpdateSubjectIdentificationSettingsMutation } from '@/hooks/useUpdateSubjectIdentificationSettingsMutation'; +import { sortByLabel } from '@/utils/sort-by-label'; import { toSubjectIdentificationDraft, toUpdateSubjectIdentificationSettingsData @@ -18,6 +22,7 @@ import { import type { SubjectIdentificationDraft } from '@/utils/subject-identification-draft'; import { CustomFieldsEditor } from './CustomFieldsEditor'; +import { OfferedMethodsSection } from './OfferedMethodsSection'; export type SubjectIdentificationSettingsFormProps = { activeLanguages: readonly Language[]; @@ -38,12 +43,21 @@ export const SubjectIdentificationSettingsForm = ({ const updateMutation = useUpdateSubjectIdentificationSettingsMutation(); const [draft, setDraft] = useState(() => toSubjectIdentificationDraft(settings)); const [showErrors, setShowErrors] = useState(false); - const [isConfirmationOpen, setIsConfirmationOpen] = useState(false); + // The checked body awaiting confirmation, so what is confirmed is exactly what is sent. + const [confirmingUpdate, setConfirmingUpdate] = useState<$UpdateSubjectIdentificationSettingsData | null>(null); - const updateData = toUpdateSubjectIdentificationSettingsData(draft); - const isValid = $UpdateSubjectIdentificationSettingsData.safeParse(updateData).success; + const parsedUpdateData = $UpdateSubjectIdentificationSettingsData.safeParse( + toUpdateSubjectIdentificationSettingsData(draft) + ); + const isValid = parsedUpdateData.success; + + // A method being turned off strands the subjects it identifies until it is offered again. + const methodsTurnedOff = settings.offeredMethods.filter((method) => !draft.offeredMethods.includes(method)); + const countsQuery = useSubjectIdentificationCountsQuery({ isEnabled: methodsTurnedOff.length > 0 }); + const { options: methodLabels } = useSubjectIdentificationMethodOptions(settings); + const isFirstDefinition = settings.customFields === null && draft.customFields !== null; - const save = async () => { + const save = async (updateData: $UpdateSubjectIdentificationSettingsData) => { const saveFailedTitle = t({ en: 'Save failed', es: 'Error al guardar', fr: "Échec de l'enregistrement" }); try { await updateMutation.mutateAsync(updateData); @@ -78,30 +92,65 @@ export const SubjectIdentificationSettingsForm = ({ }; const handleSave = () => { - if (!isValid) { + if (!parsedUpdateData.success) { setShowErrors(true); - } else if (settings.customFields === null && draft.customFields !== null) { - setIsConfirmationOpen(true); + } else if (isFirstDefinition || methodsTurnedOff.length > 0) { + setConfirmingUpdate(parsedUpdateData.data); } else { - void save(); + void save(parsedUpdateData.data); } }; - const handleConfirm = () => { - setIsConfirmationOpen(false); - void save(); - }; + const customFieldsTitle = t({ + en: 'Custom Identifying Fields', + es: 'Campos de identificación personalizados', + fr: "Champs d'identification personnalisés" + }); + const offeredMethodsTitle = t({ en: 'Offered Methods', es: 'Métodos ofrecidos', fr: 'Méthodes proposées' }); + const sections = sortByLabel([ + { + content: ( + { + setDraft((current) => ({ + customFields, + // Custom fields can be offered only while they are defined. + offeredMethods: customFields + ? current.offeredMethods + : current.offeredMethods.filter((method) => method !== 'CUSTOM_FIELDS') + })); + }} + /> + ), + key: 'custom-fields', + label: customFieldsTitle + }, + { + content: ( + setDraft((current) => ({ ...current, offeredMethods }))} + /> + ), + key: 'offered-methods', + label: offeredMethodsTitle + } + ]); return (
- setDraft((current) => ({ ...current, customFields }))} - /> + {sections.map(({ content, key }) => ( + {content} + ))}
- - - - - {t({ - en: 'Save the identifying fields?', - es: '¿Guardar los campos de identificación?', - fr: "Enregistrer les champs d'identification ?" - })} - - - {t({ - en: 'Once a subject has been identified with these fields, the field list cannot change: no field can be added, removed or moved, and the definition cannot be removed. Labels, help text, patterns and error messages stay editable.', - es: 'Una vez que se haya identificado a un sujeto con estos campos, la lista de campos no podrá cambiar: no se podrá agregar, eliminar ni mover ningún campo, ni eliminar la definición. Las etiquetas, los textos de ayuda, los patrones y los mensajes de error seguirán siendo editables.', - fr: "Dès qu'un sujet aura été identifié avec ces champs, la liste des champs ne pourra plus changer : aucun champ ne pourra être ajouté, supprimé ou déplacé, et la définition ne pourra plus être supprimée. Les étiquettes, les textes d'aide, les motifs et les messages d'erreur resteront modifiables." - })} - - - - - - - - + {confirmingUpdate && ( + setConfirmingUpdate(null)}> + + + + {t({ + en: 'Save the subject identification settings?', + es: '¿Guardar la configuración de identificación de sujetos?', + fr: "Enregistrer les paramètres d'identification des sujets ?" + })} + + {methodsTurnedOff.length > 0 && ( +
+

+ {t({ + en: 'Staff will not be able to start a session for the subjects these methods identify until the method is offered again:', + es: 'El personal no podrá iniciar una sesión para los sujetos que identifican estos métodos hasta que el método vuelva a ofrecerse:', + fr: 'Le personnel ne pourra plus démarrer de session pour les sujets identifiés par ces méthodes tant que la méthode ne sera pas de nouveau proposée :' + })} +

+
    + {methodsTurnedOff.map((method: SubjectIdentificationMethod) => ( +
  • + {t( + { en: '{}: {} subjects', es: '{}: {} sujetos', fr: '{} : {} sujets' }, + { args: [methodLabels[method], countsQuery.data?.[method] ?? '…'] } + )} +
  • + ))} +
+
+ )} + {isFirstDefinition && ( + + {t({ + en: 'Once a subject has been identified with these fields, the field list cannot change: no field can be added, removed or moved, and the definition cannot be removed. Labels, help text, patterns and error messages stay editable.', + es: 'Una vez que se haya identificado a un sujeto con estos campos, la lista de campos no podrá cambiar: no se podrá agregar, eliminar ni mover ningún campo, ni eliminar la definición. Las etiquetas, los textos de ayuda, los patrones y los mensajes de error seguirán siendo editables.', + fr: "Dès qu'un sujet aura été identifié avec ces champs, la liste des champs ne pourra plus changer : aucun champ ne pourra être ajouté, supprimé ou déplacé, et la définition ne pourra plus être supprimée. Les étiquettes, les textes d'aide, les motifs et les messages d'erreur resteront modifiables." + })} + + )} +
+ + + + +
+
+ )}
); }; diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx index 039da03b6..50eaaefff 100644 --- a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/CustomFieldsEditor.test.tsx @@ -36,6 +36,7 @@ const renderEditor = ( isDefinitionStored={isDefinitionStored} isLocked={isLocked} showErrors={showErrors} + title="Custom Identifying Fields" value={value} onChange={(next) => { onChange(next); diff --git a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx index 5f0f63859..ad18d8acd 100644 --- a/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx +++ b/apps/web/src/components/SubjectIdentificationSettingsForm/__tests__/SubjectIdentificationSettingsForm.test.tsx @@ -4,7 +4,7 @@ import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'; +import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'; import { AxiosError, AxiosHeaders } from 'axios'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; @@ -29,10 +29,17 @@ const storedSettings = (overrides: Partial = {}): salt: SALT }, isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'], ...overrides }); -const unsetSettings: SubjectIdentificationSettings = { customFields: null, isCustomFieldsLocked: false }; +const unsetSettings: SubjectIdentificationSettings = { + customFields: null, + isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] +}; + +const BUILT_IN_METHODS = ['CUSTOM_ID', 'PERSONAL_INFO']; const conflictError = () => { return new AxiosError('Conflict', 'ERR_BAD_REQUEST', undefined, undefined, { @@ -68,10 +75,13 @@ const defineOneField = () => { describe('SubjectIdentificationSettingsForm', () => { beforeEach(() => { vi.clearAllMocks(); - mockAxios.put.mockImplementation((_url, { customFields }: $UpdateSubjectIdentificationSettingsData) => { - const saved = customFields && { ...customFields, iterations: 600_000, salt: SALT }; - return Promise.resolve({ data: { customFields: saved, isCustomFieldsLocked: false } }); - }); + mockAxios.put.mockImplementation( + (_url, { customFields, offeredMethods }: $UpdateSubjectIdentificationSettingsData) => { + const saved = customFields && { ...customFields, iterations: 600_000, salt: SALT }; + return Promise.resolve({ data: { customFields: saved, isCustomFieldsLocked: false, offeredMethods } }); + } + ); + mockAxios.get.mockResolvedValue({ data: { CUSTOM_FIELDS: 0, CUSTOM_ID: 4, PERSONAL_INFO: 7 } }); useNotificationsStore.setState({ notifications: [] }); }); @@ -96,10 +106,20 @@ describe('SubjectIdentificationSettingsForm', () => { customFields: { fields: [{ description: null, label: { en: 'Animal ID' }, pattern: '[0-9]+', patternErrorMessage: null }], label: { en: 'Animal information' } - } + }, + offeredMethods: BUILT_IN_METHODS }); }); + it('should not save when the confirmation is dismissed', () => { + renderForm(unsetSettings); + defineOneField(); + click('subject-identification-save'); + fireEvent.keyDown(screen.getByTestId('subject-identification-confirm-dialog'), { key: 'Escape' }); + expect(screen.queryByTestId('subject-identification-confirm-dialog')).toBeNull(); + expect(mockAxios.put).not.toHaveBeenCalled(); + }); + it('should not save when the confirmation is cancelled', () => { renderForm(unsetSettings); defineOneField(); @@ -112,7 +132,9 @@ describe('SubjectIdentificationSettingsForm', () => { it('should save without confirmation while still no definition is drafted', async () => { renderForm(unsetSettings); click('subject-identification-save'); - await waitFor(() => expect(lastPutBody()).toStrictEqual({ customFields: null })); + await waitFor(() => { + expect(lastPutBody()).toStrictEqual({ customFields: null, offeredMethods: BUILT_IN_METHODS }); + }); }); }); @@ -156,7 +178,9 @@ describe('SubjectIdentificationSettingsForm', () => { renderForm(storedSettings()); click('custom-fields-remove'); click('subject-identification-save'); - await waitFor(() => expect(lastPutBody()).toStrictEqual({ customFields: null })); + await waitFor(() => { + expect(lastPutBody()).toStrictEqual({ customFields: null, offeredMethods: BUILT_IN_METHODS }); + }); }); it('should not offer a second save while one is in flight', async () => { @@ -170,6 +194,77 @@ describe('SubjectIdentificationSettingsForm', () => { }); }); + it('should list its sections by their translated label, as every settings tab orders its items', () => { + renderForm(storedSettings()); + const titles = screen.getAllByRole('heading', { name: /^(Custom Identifying Fields|Offered Methods)$/ }); + expect(titles.map((title) => title.textContent)).toStrictEqual(['Custom Identifying Fields', 'Offered Methods']); + }); + + describe('offered methods', () => { + it('should offer custom fields only once a definition is drafted, since only defined fields can be offered', () => { + renderForm(unsetSettings); + expect(screen.getByTestId('offered-method-CUSTOM_FIELDS').disabled).toBe(true); + defineOneField(); + expect(screen.getByTestId('offered-method-CUSTOM_FIELDS').disabled).toBe(false); + }); + + it("should label custom fields with the drafted method's label", () => { + renderForm(storedSettings()); + expect(screen.getByTestId('offered-methods').textContent).toContain('Animal information'); + }); + + it('should list the methods by their translated label, as every settings tab orders its items', () => { + renderForm(storedSettings()); + const labels = within(screen.getByTestId('offered-methods')).getAllByText( + /^(Animal information|Custom Identifier|Personal Information)$/ + ); + expect(labels.map((label) => label.textContent)).toStrictEqual([ + 'Animal information', + 'Custom Identifier', + 'Personal Information' + ]); + }); + + it('should send the ticked methods, with no confirmation when none is turned off', async () => { + renderForm(storedSettings()); + click('offered-method-CUSTOM_FIELDS'); + click('subject-identification-save'); + await waitFor(() => expect(lastNotification()?.type).toBe('success')); + expect(lastPutBody()).toMatchObject({ offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS'] }); + }); + + it('should require at least one method, or no subject could be identified', () => { + renderForm(storedSettings()); + click('offered-method-CUSTOM_ID'); + click('offered-method-PERSONAL_INFO'); + click('subject-identification-save'); + expect(screen.getByTestId('offered-methods-error')).toBeTruthy(); + expect(mockAxios.put).not.toHaveBeenCalled(); + }); + + it('should show how many subjects a method identifies before turning it off, and save it once confirmed', async () => { + renderForm(storedSettings()); + click('offered-method-PERSONAL_INFO'); + click('subject-identification-save'); + await waitFor(() => { + expect(screen.getByTestId('turn-off-count-PERSONAL_INFO').textContent).toBe('Personal Information: 7 subjects'); + }); + expect(mockAxios.get).toHaveBeenCalledWith('/v1/subjects/identification/counts'); + expect(mockAxios.put).not.toHaveBeenCalled(); + click('subject-identification-confirm-save'); + await waitFor(() => expect(lastPutBody()).toMatchObject({ offeredMethods: ['CUSTOM_ID'] })); + }); + + it('should stop offering custom fields when their definition is removed', async () => { + renderForm(storedSettings({ offeredMethods: ['CUSTOM_ID', 'CUSTOM_FIELDS'] })); + click('custom-fields-remove'); + click('subject-identification-save'); + expect(screen.getByTestId('turn-off-count-CUSTOM_FIELDS')).toBeTruthy(); + click('subject-identification-confirm-save'); + await waitFor(() => expect(lastPutBody()).toStrictEqual({ customFields: null, offeredMethods: ['CUSTOM_ID'] })); + }); + }); + describe('a failed save', () => { it('should say the changes were not saved and keep them', async () => { mockAxios.put.mockRejectedValue(new Error('Network Error')); diff --git a/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts b/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts index 285fa114b..0b1422de4 100644 --- a/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts +++ b/apps/web/src/hooks/__tests__/useCustomIdentificationFields.test.ts @@ -28,17 +28,12 @@ const renderFields = (value: CustomFieldsDefinition | null = definition) => { }; describe('useCustomIdentificationFields', () => { - it('should offer no method and no field without a definition', () => { + it('should offer no field without a definition', () => { const fields = renderFields(null); - expect(fields.label).toBeNull(); expect(fields.formFields).toStrictEqual({}); expect(fields.findErrors({})).toStrictEqual({}); }); - it("should label the method with the administrator's label", () => { - expect(renderFields().label).toBe('Animal information'); - }); - it('should key one field per defined field, in order', () => { expect(Object.keys(renderFields().formFields)).toStrictEqual(['customField0', 'customField1']); expect(Object.keys(renderFields().shape)).toStrictEqual(['customField0', 'customField1']); @@ -100,6 +95,17 @@ describe('useCustomIdentificationFields', () => { expect(renderFields().orderValues({ customField0: 'ab1', customField1: '7' })).toStrictEqual(['ab1', '7']); }); + it('should order a value not yet entered as empty, keeping every field in its place', () => { + expect(renderFields().orderValues({ customField1: '7' })).toStrictEqual(['', '7']); + }); + + it('should label a field whose label has no text in any language with nothing, rather than fail', () => { + const { formFields } = renderFields({ ...definition, fields: [{ label: {}, pattern: '[0-9]+' }] }); + expect(formFields.customField0?.render({ subjectIdentificationMethod: 'CUSTOM_FIELDS' })).toMatchObject({ + label: '' + }); + }); + it("should derive the subject id from the values in order, with the instance's salt and iterations", async () => { await expect(renderFields().deriveSubjectId({ customField0: 'ab1', customField1: '7' })).resolves.toBe( await deriveCustomFieldsSubjectId(['ab1', '7'], { iterations: 1000, salt: '0f'.repeat(32) }) diff --git a/apps/web/src/hooks/__tests__/useSubjectIdentificationCountsQuery.test.ts b/apps/web/src/hooks/__tests__/useSubjectIdentificationCountsQuery.test.ts new file mode 100644 index 000000000..e8d908d62 --- /dev/null +++ b/apps/web/src/hooks/__tests__/useSubjectIdentificationCountsQuery.test.ts @@ -0,0 +1,40 @@ +import type { PropsWithChildren } from 'react'; +import { createElement } from 'react'; + +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { renderHook, waitFor } from '@testing-library/react'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +import { useSubjectIdentificationCountsQuery } from '../useSubjectIdentificationCountsQuery'; + +const mockAxios = vi.hoisted(() => ({ get: vi.fn(), isAxiosError: vi.fn(() => false) })); + +vi.mock('axios', () => ({ default: mockAxios })); + +const counts = { CUSTOM_FIELDS: 1, CUSTOM_ID: 2, PERSONAL_INFO: 3 }; + +const renderCountsQuery = (isEnabled: boolean) => { + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + const wrapper = ({ children }: PropsWithChildren) => { + return createElement(QueryClientProvider, { client: queryClient }, children); + }; + return renderHook(() => useSubjectIdentificationCountsQuery({ isEnabled }), { wrapper }); +}; + +describe('useSubjectIdentificationCountsQuery', () => { + beforeEach(() => { + vi.clearAllMocks(); + mockAxios.get.mockResolvedValue({ data: counts }); + }); + + it('should request the counts and parse them at the boundary', async () => { + const { result } = renderCountsQuery(true); + await waitFor(() => expect(result.current.data).toStrictEqual(counts)); + expect(mockAxios.get).toHaveBeenCalledWith('/v1/subjects/identification/counts'); + }); + + it('should not count anything while no method is being turned off', () => { + renderCountsQuery(false); + expect(mockAxios.get).not.toHaveBeenCalled(); + }); +}); diff --git a/apps/web/src/hooks/__tests__/useSubjectIdentificationMethodOptions.test.ts b/apps/web/src/hooks/__tests__/useSubjectIdentificationMethodOptions.test.ts new file mode 100644 index 000000000..6c3f9f4c9 --- /dev/null +++ b/apps/web/src/hooks/__tests__/useSubjectIdentificationMethodOptions.test.ts @@ -0,0 +1,51 @@ +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; +import { renderHook } from '@testing-library/react'; +import { describe, expect, it } from 'vitest'; + +import { useSubjectIdentificationMethodOptions } from '../useSubjectIdentificationMethodOptions'; + +import '@/services/i18n'; + +const customFields = { + fields: [{ label: { en: 'Animal ID' }, pattern: '[0-9]+' }], + iterations: 1000, + label: { en: 'Animal information' }, + salt: '0f'.repeat(32) +}; + +const renderOptions = (settings: Pick) => { + return renderHook(() => useSubjectIdentificationMethodOptions(settings)).result.current; +}; + +describe('useSubjectIdentificationMethodOptions', () => { + it('should offer only the offered methods, in the order offered', () => { + expect(renderOptions({ customFields: null, offeredMethods: ['PERSONAL_INFO'] }).options).toStrictEqual({ + PERSONAL_INFO: 'Personal Information' + }); + }); + + it("should label custom fields with the administrator's label", () => { + expect(renderOptions({ customFields, offeredMethods: ['CUSTOM_ID', 'CUSTOM_FIELDS'] }).options).toStrictEqual({ + CUSTOM_FIELDS: 'Animal information', + CUSTOM_ID: 'Custom Identifier' + }); + }); + + it('should open a form on the preferred method while it is offered', () => { + expect( + renderOptions({ customFields, offeredMethods: ['CUSTOM_ID', 'CUSTOM_FIELDS'] }).preferMethod('CUSTOM_FIELDS') + ).toBe('CUSTOM_FIELDS'); + }); + + it('should fall back to the first offered method when the preferred one is not offered', () => { + expect(renderOptions({ customFields: null, offeredMethods: ['PERSONAL_INFO'] }).preferMethod('CUSTOM_ID')).toBe( + 'PERSONAL_INFO' + ); + }); + + it('should fall back to the first offered method when none is preferred', () => { + expect(renderOptions({ customFields: null, offeredMethods: ['PERSONAL_INFO'] }).preferMethod(undefined)).toBe( + 'PERSONAL_INFO' + ); + }); +}); diff --git a/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts b/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts index a12840e24..efb67ee97 100644 --- a/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts +++ b/apps/web/src/hooks/__tests__/useSubjectIdentificationSettingsQuery.test.ts @@ -18,7 +18,8 @@ const settings = { label: { en: 'Animal information' }, salt: 'ab'.repeat(32) }, - isCustomFieldsLocked: false + isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }; function renderSettingsQuery() { diff --git a/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts b/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts index 48380546e..d4f907a24 100644 --- a/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts +++ b/apps/web/src/hooks/__tests__/useUpdateSubjectIdentificationSettingsMutation.test.ts @@ -18,7 +18,8 @@ const definition = { const savedSettings = { customFields: { ...definition, iterations: 600_000, salt: 'ab'.repeat(32) }, - isCustomFieldsLocked: false + isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }; function renderUpdateMutation() { @@ -37,10 +38,10 @@ describe('useUpdateSubjectIdentificationSettingsMutation', () => { it('should put the settings without raising the default error toast, since the tab says why a save failed', async () => { const { result } = renderUpdateMutation(); - await result.current.mutateAsync({ customFields: definition }); + await result.current.mutateAsync({ customFields: definition, offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }); expect(mockAxios.put).toHaveBeenCalledWith( '/v1/subjects/identification/settings', - { customFields: definition }, + { customFields: definition, offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }, { meta: { disableDefaultErrorNotification: true } } ); }); @@ -49,7 +50,7 @@ describe('useUpdateSubjectIdentificationSettingsMutation', () => { // saved definition as soon as the first save returns. it('should seed the settings cache from the response', async () => { const { queryClient, result } = renderUpdateMutation(); - await result.current.mutateAsync({ customFields: definition }); + await result.current.mutateAsync({ customFields: definition, offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] }); expect(queryClient.getQueryData(['subject-identification-settings'])).toStrictEqual(savedSettings); }); }); diff --git a/apps/web/src/hooks/useCustomIdentificationFields.ts b/apps/web/src/hooks/useCustomIdentificationFields.ts index 78d7ccce2..a6a67f970 100644 --- a/apps/web/src/hooks/useCustomIdentificationFields.ts +++ b/apps/web/src/hooks/useCustomIdentificationFields.ts @@ -108,7 +108,6 @@ export function useCustomIdentificationFields(definition: CustomFieldsDefinition }, findErrors, formFields, - label: definition ? (localize(definition.label) ?? '') : null, orderValues, shape }; diff --git a/apps/web/src/hooks/useSubjectIdentificationCountsQuery.ts b/apps/web/src/hooks/useSubjectIdentificationCountsQuery.ts new file mode 100644 index 000000000..89525e027 --- /dev/null +++ b/apps/web/src/hooks/useSubjectIdentificationCountsQuery.ts @@ -0,0 +1,18 @@ +import { $SubjectIdentificationCounts } from '@opendatacapture/schemas/subject-identification'; +import { queryOptions, useQuery } from '@tanstack/react-query'; +import axios from 'axios'; + +export const subjectIdentificationCountsQueryOptions = () => { + return queryOptions({ + queryFn: async () => { + const response = await axios.get('/v1/subjects/identification/counts'); + return $SubjectIdentificationCounts.parseAsync(response.data); + }, + queryKey: ['subject-identification-counts'] + }); +}; + +/** Fetched only while `isEnabled`, which is while an administrator is about to turn a method off. */ +export function useSubjectIdentificationCountsQuery({ isEnabled }: { isEnabled: boolean }) { + return useQuery({ ...subjectIdentificationCountsQueryOptions(), enabled: isEnabled }); +} diff --git a/apps/web/src/hooks/useSubjectIdentificationMethodOptions.ts b/apps/web/src/hooks/useSubjectIdentificationMethodOptions.ts new file mode 100644 index 000000000..478d1a404 --- /dev/null +++ b/apps/web/src/hooks/useSubjectIdentificationMethodOptions.ts @@ -0,0 +1,28 @@ +import { useTranslation } from '@douglasneuroinformatics/libui/hooks'; +import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; +import type { SubjectIdentificationSettings } from '@opendatacapture/schemas/subject-identification'; + +import { getValueForLanguage } from '@/utils/language'; + +/** + * The identification methods the instance offers, as a select's options in the reader's language, + * and the method a form opens on: the one preferred while it is offered, else the first offered. + */ +export function useSubjectIdentificationMethodOptions({ + customFields, + offeredMethods +}: Pick) { + const { resolvedLanguage, t } = useTranslation(); + const labels: { [K in SubjectIdentificationMethod]: string } = { + // Offered only while defined, so the empty label is never shown. + CUSTOM_FIELDS: (customFields && getValueForLanguage(customFields.label, resolvedLanguage)) ?? '', + CUSTOM_ID: t('common.customIdentifier'), + PERSONAL_INFO: t('common.personalInfo') + }; + return { + options: Object.fromEntries(offeredMethods.map((method) => [method, labels[method]])), + preferMethod: (method: null | SubjectIdentificationMethod | undefined): SubjectIdentificationMethod => { + return method && offeredMethods.includes(method) ? method : offeredMethods[0]; + } + }; +} diff --git a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx index c26caeb6e..c92e868f6 100644 --- a/apps/web/src/routes/_app/group/__tests__/manage.test.tsx +++ b/apps/web/src/routes/_app/group/__tests__/manage.test.tsx @@ -2,6 +2,7 @@ import type { ReactNode } from 'react'; import type { $UpdateGroupData, Group } from '@opendatacapture/schemas/group'; import type { CreateSeriesInstrumentResult, TranslatedInstrumentInfo } from '@opendatacapture/schemas/instrument'; +import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; import type { CustomFieldsDefinition } from '@opendatacapture/schemas/subject-identification'; import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; @@ -31,6 +32,7 @@ const mocks = vi.hoisted(() => ({ fetchedGroup: undefined as Group | undefined, instruments: undefined as TranslatedInstrumentInfo[] | undefined, isDemo: false, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] as [SubjectIdentificationMethod, ...SubjectIdentificationMethod[]], store: { currentGroup: null as Group | null }, updateMutateAsync: vi.fn<(data: Partial<$UpdateGroupData>) => Promise>() })); @@ -53,7 +55,9 @@ vi.mock('@/hooks/useSetupStateQuery', () => ({ })); vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', async (importOriginal) => ({ ...(await importOriginal()), - useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: mocks.customFields } }) + useSubjectIdentificationSettingsQuery: () => ({ + data: { customFields: mocks.customFields, offeredMethods: mocks.offeredMethods } + }) })); vi.mock('@/hooks/useUpdateGroupMutation', () => ({ useUpdateGroupMutation: () => ({ mutateAsync: mocks.updateMutateAsync }) @@ -209,6 +213,7 @@ describe('Route', () => { vi.clearAllMocks(); mocks.customFields = null; mocks.fetchedGroup = undefined; + mocks.offeredMethods = ['CUSTOM_ID', 'PERSONAL_INFO']; mocks.instruments = defaultInstruments(); mocks.isDemo = false; mocks.store.currentGroup = makeGroup(); @@ -677,7 +682,8 @@ describe('Route', () => { expect(mocks.updateMutateAsync).toHaveBeenCalledWith( expect.objectContaining({ settings: { - defaultIdentificationMethod: 'PERSONAL_INFO', + // Unchanged, so the stored one stays. + defaultIdentificationMethod: undefined, idValidationRegex: '^[0-9]+$', idValidationRegexErrorMessage: { en: 'Digits only', fr: 'Chiffres seulement' }, minimumAge: 18, @@ -721,6 +727,12 @@ describe('Route', () => { }); describe('default identification method', () => { + /** Opens the select from the keyboard, since happy-dom dispatches no pointer capture. */ + const chooseDefaultMethod = (method: string) => { + fireEvent.keyDown(screen.getByTestId('defaultIdentificationMethod-select-trigger'), { key: 'Enter' }); + fireEvent.click(screen.getByTestId(`defaultIdentificationMethod-select-item-${method}`)); + }; + const methodOptions = () => { const select = document.querySelector('select[name="defaultIdentificationMethod"]')!; return Array.from(select.options, (option) => option.textContent).filter(Boolean); @@ -738,15 +750,34 @@ describe('Route', () => { label: { en: 'Animal information' }, salt: '0f'.repeat(32) }; - mocks.store.currentGroup = makeGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_FIELDS' } }); + mocks.offeredMethods = ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS']; renderPage(); expect(methodOptions()).toEqual(['Custom Identifier', 'Personal Information', 'Animal information']); + chooseDefaultMethod('CUSTOM_FIELDS'); submitSettings(); await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); expect(mocks.updateMutateAsync.mock.lastCall?.[0].settings?.defaultIdentificationMethod).toBe('CUSTOM_FIELDS'); }); }); + describe('offered methods', () => { + it('should offer only the methods the instance offers as the default', () => { + mocks.offeredMethods = ['PERSONAL_INFO']; + mocks.store.currentGroup = makeGroup({ settings: { defaultIdentificationMethod: 'PERSONAL_INFO' } }); + renderPage(); + const select = document.querySelector('select[name="defaultIdentificationMethod"]')!; + expect(Array.from(select.options, (option) => option.value).filter(Boolean)).toEqual(['PERSONAL_INFO']); + }); + + it('should keep a default the instance no longer offers when the manager leaves the select as it was', async () => { + mocks.offeredMethods = ['PERSONAL_INFO']; + renderPage(); + submitSettings(); + await waitFor(() => expect(mocks.updateMutateAsync).toHaveBeenCalled()); + expect(mocks.updateMutateAsync.mock.lastCall?.[0].settings?.defaultIdentificationMethod).toBeUndefined(); + }); + }); + describe('session instrument', () => { const requiring = (sessionInstrumentId: string) => { return makeGroup({ settings: { defaultIdentificationMethod: 'CUSTOM_ID', sessionInstrumentId } }); diff --git a/apps/web/src/routes/_app/group/manage.tsx b/apps/web/src/routes/_app/group/manage.tsx index 134128ff2..365cb0ec3 100644 --- a/apps/web/src/routes/_app/group/manage.tsx +++ b/apps/web/src/routes/_app/group/manage.tsx @@ -32,13 +32,13 @@ import { useDeleteSeriesInstrumentMutation } from '@/hooks/useDeleteSeriesInstru import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { useInstrumentInfoQuery } from '@/hooks/useInstrumentInfoQuery'; import { useSetupStateQuery } from '@/hooks/useSetupStateQuery'; +import { useSubjectIdentificationMethodOptions } from '@/hooks/useSubjectIdentificationMethodOptions'; import { subjectIdentificationSettingsQueryOptions, useSubjectIdentificationSettingsQuery } from '@/hooks/useSubjectIdentificationSettingsQuery'; import { useUpdateGroupMutation } from '@/hooks/useUpdateGroupMutation'; import { useAppStore } from '@/store'; -import { getValueForLanguage } from '@/utils/language'; import { buildSeriesAvailability } from '@/utils/series-availability'; /** @@ -100,8 +100,6 @@ type SettingsValues = { }; type ManageGroupFormProps = { - /** The admin's label for the custom fields, or null while none are defined, which leaves the method unavailable. */ - customFieldsLabel: null | string; data: { // The titles of every visible instrument, used to enforce unique new series instrument names. existingTitles: string[]; @@ -112,6 +110,7 @@ type ManageGroupFormProps = { instruments: CategorizedInstruments; settingsInitialValues: SettingsValues; }; + identificationMethodOptions: { [method: string]: string }; onSubmit: (data: Partial<$UpdateGroupData>) => Promisable; readOnly: boolean; }; @@ -568,7 +567,7 @@ const DeleteInstrumentDialog = ({ ); }; -const ManageGroupForm = ({ customFieldsLabel, data, onSubmit, readOnly }: ManageGroupFormProps) => { +const ManageGroupForm = ({ data, identificationMethodOptions, onSubmit, readOnly }: ManageGroupFormProps) => { const { existingTitles, groupId, hiddenAccessibleIds, initialSelectedIds, instruments, settingsInitialValues } = data; const { t } = useTranslation(); const [search, setSearch] = useState(''); @@ -605,12 +604,6 @@ const ManageGroupForm = ({ customFieldsLabel, data, onSubmit, readOnly }: Manage [instruments] ); - const identificationMethodOptions: { [method: string]: string } = { - CUSTOM_ID: t('common.customIdentifier'), - PERSONAL_INFO: t('common.personalInfo'), - ...(customFieldsLabel === null ? {} : { CUSTOM_FIELDS: customFieldsLabel }) - }; - // Only a form the group will be able to access may be required, so the options follow the selection. // The list holds the latest edition of each form, so a shared title is two forms, told apart by name. const selectedForms = instruments.form.filter((item) => selectedIds.has(item.id)); @@ -896,10 +889,13 @@ const ManageGroupForm = ({ customFieldsLabel, data, onSubmit, readOnly }: Manage }) ].filter((id) => !deletedIds.has(id)), settings: { - // The select holds a string, since which methods it offers is known only at runtime. - defaultIdentificationMethod: $SubjectIdentificationMethod - .optional() - .parse(formData.defaultIdentificationMethod), + // Left as seeded, the select may show the first offered method in place of a default the + // instance no longer offers, so it is sent only once changed; unsent, the stored one stays. + // It holds a string, since which methods it offers is known only at runtime. + defaultIdentificationMethod: + formData.defaultIdentificationMethod === settingsInitialValues.defaultIdentificationMethod + ? undefined + : $SubjectIdentificationMethod.optional().parse(formData.defaultIdentificationMethod), idValidationRegex: formData.idValidationRegex, idValidationRegexErrorMessage: { en: formData.idValidationRegexErrorMessageEn, @@ -929,10 +925,15 @@ const RouteComponent = () => { const groupQuery = useGroupQuery(currentGroup?.id); const group = groupQuery.data; const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); - const customFieldsDefinition = subjectIdentificationSettingsQuery.data.customFields; + const { options: identificationMethodOptions, preferMethod } = useSubjectIdentificationMethodOptions( + subjectIdentificationSettingsQuery.data + ); const availableInstruments = instrumentInfoQuery.data; + // A default the instance no longer offers would leave the select empty, so it shows the first offered. + const defaultIdentificationMethod = preferMethod(group?.settings.defaultIdentificationMethod); + const data = useMemo(() => { if (!availableInstruments || !group) { return null; @@ -998,7 +999,7 @@ const RouteComponent = () => { const settings = group.settings; const settingsInitialValues: SettingsValues = { - defaultIdentificationMethod: settings.defaultIdentificationMethod, + defaultIdentificationMethod, idValidationRegex: settings.idValidationRegex, idValidationRegexErrorMessageEn: settings.idValidationRegexErrorMessage?.en, idValidationRegexErrorMessageFr: settings.idValidationRegexErrorMessage?.fr, @@ -1020,7 +1021,7 @@ const RouteComponent = () => { instruments, settingsInitialValues }; - }, [availableInstruments, group, resolvedLanguage, t]); + }, [availableInstruments, defaultIdentificationMethod, group, resolvedLanguage, t]); return ( @@ -1035,10 +1036,8 @@ const RouteComponent = () => { Component={ManageGroupForm} key={currentGroup?.id} props={{ - customFieldsLabel: customFieldsDefinition - ? (getValueForLanguage(customFieldsDefinition.label, resolvedLanguage) ?? '') - : null, data, + identificationMethodOptions, onSubmit: async (data) => { const updatedGroup = await updateGroupMutation.mutateAsync(data); changeGroup(updatedGroup); diff --git a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx index 44d5c5bc2..8bfe7da72 100644 --- a/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx +++ b/apps/web/src/routes/_app/session/__tests__/start-session.test.tsx @@ -12,11 +12,11 @@ import '@/services/i18n'; type StartSessionFormProps = { currentGroup: Group | null; - customFieldsDefinition: unknown; customSubjectIds: string[]; initialValues: { [key: string]: unknown }; onSubmit: (data: $CreateSessionData) => Promise; readOnly: boolean; + subjectIdentificationSettings: unknown; username?: string; }; @@ -34,6 +34,7 @@ type MockState = { fetchedGroup: Group | null; isPending: boolean; locationState: undefined | { initialValues?: { [key: string]: unknown } }; + offeredMethods: [string, ...string[]]; store: { currentGroup: Group | null; currentSession: null | Session; @@ -47,6 +48,7 @@ const mocks = vi.hoisted(() => { fetchedGroup: null, isPending: false, locationState: undefined, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS'], store: { currentGroup: null, currentSession: null, currentUser: null, startSession: vi.fn() } }; return { @@ -73,7 +75,9 @@ vi.mock('@/hooks/useGroupQuery', async (importOriginal) => ({ })); vi.mock('@/hooks/useSubjectIdentificationSettingsQuery', async (importOriginal) => ({ ...(await importOriginal()), - useSubjectIdentificationSettingsQuery: () => ({ data: { customFields: CUSTOM_FIELDS, isCustomFieldsLocked: false } }) + useSubjectIdentificationSettingsQuery: () => ({ + data: { customFields: CUSTOM_FIELDS, isCustomFieldsLocked: false, offeredMethods: mocks.offeredMethods } + }) })); vi.mock('@/hooks/useSubjectCustomIdsQuery', async (importOriginal) => ({ ...(await importOriginal()), @@ -127,6 +131,7 @@ const formProps = () => mocks.StartSessionForm.mock.lastCall![0]; describe('Route', () => { beforeEach(() => { mocks.fetchedGroup = group; + mocks.offeredMethods = ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS']; mocks.isPending = false; mocks.locationState = undefined; mocks.store.currentGroup = group; @@ -159,7 +164,7 @@ describe('Route', () => { it("should hand the form the instance's custom identifying fields", () => { render(); - expect(formProps().customFieldsDefinition).toBe(CUSTOM_FIELDS); + expect(formProps().subjectIdentificationSettings).toMatchObject({ customFields: CUSTOM_FIELDS }); }); it('should suggest the custom ids of the group with their group scope removed', () => { @@ -181,6 +186,12 @@ describe('Route', () => { }); }); + it("should open on the first offered method when the group's preferred one is not offered", () => { + mocks.offeredMethods = ['CUSTOM_FIELDS']; + render(); + expect(formProps().initialValues).toMatchObject({ subjectIdentificationMethod: 'CUSTOM_FIELDS' }); + }); + it('should default to identifying by custom id when there is no group', () => { mocks.store.currentGroup = null; render(); diff --git a/apps/web/src/routes/_app/session/start-session.tsx b/apps/web/src/routes/_app/session/start-session.tsx index 0371778e5..f1a5b7ba9 100644 --- a/apps/web/src/routes/_app/session/start-session.tsx +++ b/apps/web/src/routes/_app/session/start-session.tsx @@ -15,6 +15,7 @@ import type { StartSessionFormData } from '@/components/StartSessionForm'; import { useCreateSessionMutation } from '@/hooks/useCreateSessionMutation'; import { groupQueryOptions, useGroupQuery } from '@/hooks/useGroupQuery'; import { subjectCustomIdsQueryOptions, useSubjectCustomIdsQuery } from '@/hooks/useSubjectCustomIdsQuery'; +import { useSubjectIdentificationMethodOptions } from '@/hooks/useSubjectIdentificationMethodOptions'; import { subjectIdentificationSettingsQueryOptions, useSubjectIdentificationSettingsQuery @@ -32,9 +33,11 @@ const RouteComponent = () => { const startSession = useAppStore((store) => store.startSession); const currentUser = useAppStore((store) => store.currentUser); const location = useLocation(); + const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); + const { preferMethod } = useSubjectIdentificationMethodOptions(subjectIdentificationSettingsQuery.data); const defaultInitialValues = { sessionType: 'IN_PERSON', - subjectIdentificationMethod: currentGroup?.settings.defaultIdentificationMethod ?? 'CUSTOM_ID' + subjectIdentificationMethod: preferMethod(currentGroup?.settings.defaultIdentificationMethod ?? 'CUSTOM_ID') } as const; const [initialValues, setInitialValues] = useState>( location.state?.initialValues ?? defaultInitialValues @@ -46,7 +49,6 @@ const RouteComponent = () => { const subjectCustomIdsQuery = useSubjectCustomIdsQuery({ params: { groupId: currentGroup?.id } }); // The store holds the group as it was at sign-in, so a session instrument chosen since is read fresh. const groupQuery = useGroupQuery(currentGroup?.id); - const subjectIdentificationSettingsQuery = useSubjectIdentificationSettingsQuery(); const customSubjectIds = subjectCustomIdsQuery.data.map(removeSubjectIdScope); @@ -79,10 +81,10 @@ const RouteComponent = () => {
{ const sessionInstrumentId = groupQuery.data?.settings.sessionInstrumentId; diff --git a/apps/web/src/utils/__tests__/subject-identification-draft.test.ts b/apps/web/src/utils/__tests__/subject-identification-draft.test.ts index ad7cd14fb..0e636f1f8 100644 --- a/apps/web/src/utils/__tests__/subject-identification-draft.test.ts +++ b/apps/web/src/utils/__tests__/subject-identification-draft.test.ts @@ -22,7 +22,8 @@ const settings: SubjectIdentificationSettings = { label: { en: 'Animal information' }, salt: 'ab'.repeat(32) }, - isCustomFieldsLocked: false + isCustomFieldsLocked: false, + offeredMethods: ['CUSTOM_ID', 'CUSTOM_FIELDS'] }; const field = (overrides: Partial = {}): CustomFieldDraft => ({ @@ -56,22 +57,28 @@ describe('toSubjectIdentificationDraft', () => { }); it('should hold no definition when none is stored', () => { - expect(toSubjectIdentificationDraft({ customFields: null, isCustomFieldsLocked: false })).toStrictEqual({ - customFields: null - }); + expect( + toSubjectIdentificationDraft({ customFields: null, isCustomFieldsLocked: false, offeredMethods: ['CUSTOM_ID'] }) + ).toStrictEqual({ customFields: null, offeredMethods: ['CUSTOM_ID'] }); + }); + + it('should hold the offered methods', () => { + expect(toSubjectIdentificationDraft(settings).offeredMethods).toStrictEqual(['CUSTOM_ID', 'CUSTOM_FIELDS']); }); }); describe('toUpdateSubjectIdentificationSettingsData', () => { it('should send the fields without their keys and with blank languages left out', () => { const data = toUpdateSubjectIdentificationSettingsData({ - customFields: { fields: [field({ label: { en: 'Animal ID', fr: ' ' } })], label: { en: 'Animal', es: '' } } + customFields: { fields: [field({ label: { en: 'Animal ID', fr: ' ' } })], label: { en: 'Animal', es: '' } }, + offeredMethods: ['CUSTOM_ID'] }); expect(data).toStrictEqual({ customFields: { fields: [{ description: null, label: { en: 'Animal ID' }, pattern: '[0-9]+', patternErrorMessage: null }], label: { en: 'Animal' } - } + }, + offeredMethods: ['CUSTOM_ID'] }); }); @@ -80,7 +87,8 @@ describe('toUpdateSubjectIdentificationSettingsData', () => { customFields: { fields: [field({ description: { fr: 'Aide' }, patternErrorMessage: { es: 'Error' } })], label: {} - } + }, + offeredMethods: ['CUSTOM_ID'] }); expect(data.customFields?.fields[0]).toMatchObject({ description: { fr: 'Aide' }, @@ -89,7 +97,12 @@ describe('toUpdateSubjectIdentificationSettingsData', () => { }); it('should send a removed definition as null', () => { - expect(toUpdateSubjectIdentificationSettingsData({ customFields: null })).toStrictEqual({ customFields: null }); + expect( + toUpdateSubjectIdentificationSettingsData({ customFields: null, offeredMethods: ['CUSTOM_ID'] }) + ).toStrictEqual({ + customFields: null, + offeredMethods: ['CUSTOM_ID'] + }); }); }); diff --git a/apps/web/src/utils/subject-identification-draft.ts b/apps/web/src/utils/subject-identification-draft.ts index 36d7dd165..f5025b01f 100644 --- a/apps/web/src/utils/subject-identification-draft.ts +++ b/apps/web/src/utils/subject-identification-draft.ts @@ -1,4 +1,5 @@ import type { LocalizedString } from '@opendatacapture/schemas/core'; +import type { SubjectIdentificationMethod } from '@opendatacapture/schemas/subject'; import { $CustomFieldsDefinitionData, $CustomIdentificationField @@ -24,6 +25,15 @@ type CustomFieldsDraft = Omit & { fields: */ type SubjectIdentificationDraft = { customFields: CustomFieldsDraft | null; + offeredMethods: SubjectIdentificationMethod[]; +}; + +/** + * The body the draft would send, before the schema has checked it: the draft may offer no method + * while it is being edited, which the schema refuses. + */ +type UncheckedSubjectIdentificationSettingsData = Omit<$UpdateSubjectIdentificationSettingsData, 'offeredMethods'> & { + offeredMethods: SubjectIdentificationMethod[]; }; type CustomFieldIssues = { @@ -36,11 +46,15 @@ const createCustomFieldDraft = (): CustomFieldDraft => ({ key: crypto.randomUUID /** A definition has at least one field, so a new one starts with a field to fill in. */ const createCustomFieldsDraft = (): CustomFieldsDraft => ({ fields: [createCustomFieldDraft()], label: {} }); -const toSubjectIdentificationDraft = ({ customFields }: SubjectIdentificationSettings): SubjectIdentificationDraft => ({ +const toSubjectIdentificationDraft = ({ + customFields, + offeredMethods +}: SubjectIdentificationSettings): SubjectIdentificationDraft => ({ customFields: customFields && { fields: customFields.fields.map((field) => ({ ...field, key: crypto.randomUUID() })), label: customFields.label - } + }, + offeredMethods }); const omitBlankOptionalText = (value: LocalizedString | null | undefined): LocalizedString | null => { @@ -48,8 +62,9 @@ const omitBlankOptionalText = (value: LocalizedString | null | undefined): Local }; const toUpdateSubjectIdentificationSettingsData = ({ - customFields -}: SubjectIdentificationDraft): $UpdateSubjectIdentificationSettingsData => ({ + customFields, + offeredMethods +}: SubjectIdentificationDraft): UncheckedSubjectIdentificationSettingsData => ({ customFields: customFields && { fields: customFields.fields.map(({ description, label, pattern, patternErrorMessage }) => ({ description: omitBlankOptionalText(description), @@ -58,7 +73,8 @@ const toUpdateSubjectIdentificationSettingsData = ({ patternErrorMessage: omitBlankOptionalText(patternErrorMessage) })), label: omitBlankLanguages(customFields.label) - } + }, + offeredMethods }); // The schema decides what is invalid; the editor only decides where to say so. @@ -80,4 +96,10 @@ export { toUpdateSubjectIdentificationSettingsData }; -export type { CustomFieldDraft, CustomFieldIssues, CustomFieldsDraft, SubjectIdentificationDraft }; +export type { + CustomFieldDraft, + CustomFieldIssues, + CustomFieldsDraft, + SubjectIdentificationDraft, + UncheckedSubjectIdentificationSettingsData +}; diff --git a/docs/en/4-concepts/4.2-hash-based-identification.md b/docs/en/4-concepts/4.2-hash-based-identification.md index c26e96a41..8e87e842f 100644 --- a/docs/en/4-concepts/4.2-hash-based-identification.md +++ b/docs/en/4-concepts/4.2-hash-based-identification.md @@ -64,6 +64,8 @@ An administrator can define an instance's own identifying fields instead, for ex The administrator defines the fields once, under **Admin Panel** > **Instance** > **Settings**, on the **Subject Identification** tab. Each field has a label, optional help text, a pattern the value must match and an optional message shown when it does not. The values typed are never sent to the server and never stored; your browser derives the identifier from them, and a subject who returns is recognized when the same values are typed again. +On the same tab, the administrator chooses which methods staff are offered. Defining the fields does not offer them by itself; they are offered once **Offered Methods** includes them. A method that is not offered disappears from Start Session, the subject lookup and each group's default method, and a group whose default method is not offered starts on the first method that is. Turning a method off changes no subject's identifier, so it can be undone, but staff cannot start a session for the subjects it identifies until it is offered again; the page says how many subjects that is before it saves. + ### How the identifier is derived Your browser standardizes each value: diff --git a/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts b/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts index c8ba6f72e..d66d9be6f 100644 --- a/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts +++ b/packages/schemas/src/subject-identification/__tests__/subject-identification.test.ts @@ -12,7 +12,10 @@ const update = ( fields: { [key: string]: unknown }[], label: { [key: string]: unknown } = { en: 'Animal information' } ) => { - return $UpdateSubjectIdentificationSettingsData.safeParse({ customFields: { fields, label } }); + return $UpdateSubjectIdentificationSettingsData.safeParse({ + customFields: { fields, label }, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO'] + }); }; describe('$UpdateSubjectIdentificationSettingsData', () => { @@ -21,7 +24,11 @@ describe('$UpdateSubjectIdentificationSettingsData', () => { }); it('should accept removing the definition', () => { - expect($UpdateSubjectIdentificationSettingsData.safeParse({ customFields: null }).success).toBe(true); + const result = $UpdateSubjectIdentificationSettingsData.safeParse({ + customFields: null, + offeredMethods: ['CUSTOM_ID'] + }); + expect(result.success).toBe(true); }); it('should reject a definition with no field, which would give every subject the same id', () => { @@ -51,13 +58,39 @@ describe('$UpdateSubjectIdentificationSettingsData', () => { it('should ignore a salt or iteration count sent by the client, since only the server sets them', () => { const result = $UpdateSubjectIdentificationSettingsData.parse({ - customFields: { fields: [field()], iterations: 1, label: { en: 'Animal information' }, salt: '00' } + customFields: { fields: [field()], iterations: 1, label: { en: 'Animal information' }, salt: '00' }, + offeredMethods: ['CUSTOM_ID'] }); expect(result.customFields).not.toHaveProperty('salt'); expect(result.customFields).not.toHaveProperty('iterations'); }); }); +describe('$UpdateSubjectIdentificationSettingsData.offeredMethods', () => { + const offer = ( + offeredMethods: string[], + customFields: null | object = { fields: [field()], label: { en: 'Animals' } } + ) => { + return $UpdateSubjectIdentificationSettingsData.safeParse({ customFields, offeredMethods }).success; + }; + + it('should require at least one method, or no subject could be identified', () => { + expect(offer([])).toBe(false); + }); + + it('should refuse a method offered twice', () => { + expect(offer(['CUSTOM_ID', 'CUSTOM_ID'])).toBe(false); + }); + + it('should refuse to offer custom fields that are not defined', () => { + expect(offer(['CUSTOM_FIELDS'], null)).toBe(false); + }); + + it('should offer custom fields once they are defined', () => { + expect(offer(['CUSTOM_FIELDS'])).toBe(true); + }); +}); + describe('compileCustomFieldPattern', () => { it('should match only the whole value, so a pattern cannot accept a value by matching part of it', () => { const pattern = compileCustomFieldPattern('[0-9]{3}'); diff --git a/packages/schemas/src/subject-identification/subject-identification.ts b/packages/schemas/src/subject-identification/subject-identification.ts index 31fb93e29..2200b808a 100644 --- a/packages/schemas/src/subject-identification/subject-identification.ts +++ b/packages/schemas/src/subject-identification/subject-identification.ts @@ -1,6 +1,9 @@ import { z } from 'zod/v4'; import { $AuthoredLocalizedString, $LocalizedString } from '../core/core.js'; +import { $SubjectIdentificationMethod } from '../subject/subject.js'; + +import type { SubjectIdentificationMethod } from '../subject/subject.js'; // ── Internal helpers (must precede all exports for import/exports-last) ─────── @@ -46,15 +49,46 @@ const $CustomFieldsDefinition = $CustomFieldsDefinitionData.extend({ salt: z.string() }); +// A tuple, so the type carries what the schema checks: a form can always fall back to the first. +const $OfferedSubjectIdentificationMethods = z + .tuple([$SubjectIdentificationMethod], $SubjectIdentificationMethod) + .refine((methods) => new Set(methods).size === methods.length, 'Each method may be offered only once'); + +/** What an instance offers until an administrator chooses otherwise. */ +const DEFAULT_OFFERED_SUBJECT_IDENTIFICATION_METHODS: z.infer = [ + 'CUSTOM_ID', + 'PERSONAL_INFO' +]; + const $SubjectIdentificationSettings = z.object({ customFields: $CustomFieldsDefinition.nullable(), /** Once a subject has an id derived from the fields, their number and order can never change. */ - isCustomFieldsLocked: z.boolean() + isCustomFieldsLocked: z.boolean(), + offeredMethods: $OfferedSubjectIdentificationMethods }); -const $UpdateSubjectIdentificationSettingsData = z.object({ - customFields: $CustomFieldsDefinitionData.nullable() -}); +const $UpdateSubjectIdentificationSettingsData = z + .object({ + customFields: $CustomFieldsDefinitionData.nullable(), + offeredMethods: $OfferedSubjectIdentificationMethods + }) + .check((ctx) => { + if (ctx.value.offeredMethods.includes('CUSTOM_FIELDS') && !ctx.value.customFields) { + ctx.issues.push({ + code: 'custom', + input: ctx.value.offeredMethods, + message: 'Custom fields can be offered only once they are defined', + path: ['offeredMethods'] + }); + } + }); + +/** How many subjects are identified by each method, told apart by the shape of their ids. */ +const $SubjectIdentificationCounts = z.object({ + CUSTOM_FIELDS: z.number().int().nonnegative(), + CUSTOM_ID: z.number().int().nonnegative(), + PERSONAL_INFO: z.number().int().nonnegative() +} satisfies { [K in SubjectIdentificationMethod]: z.ZodType }); type CustomIdentificationField = z.infer; @@ -64,22 +98,30 @@ type CustomFieldsDefinition = z.infer; type SubjectIdentificationSettings = z.infer; +type SubjectIdentificationCounts = z.infer; + +type OfferedSubjectIdentificationMethods = z.infer; + type $UpdateSubjectIdentificationSettingsData = z.infer; export { $CustomFieldsDefinition, $CustomFieldsDefinitionData, $CustomIdentificationField, + $SubjectIdentificationCounts, $SubjectIdentificationSettings, $UpdateSubjectIdentificationSettingsData, compileCustomFieldPattern, CUSTOM_FIELD_MAX_VALUE_LENGTH, - CUSTOM_FIELDS_MAX_FIELD_COUNT + CUSTOM_FIELDS_MAX_FIELD_COUNT, + DEFAULT_OFFERED_SUBJECT_IDENTIFICATION_METHODS }; export type { CustomFieldsDefinition, CustomFieldsDefinitionData, CustomIdentificationField, + OfferedSubjectIdentificationMethods, + SubjectIdentificationCounts, SubjectIdentificationSettings }; diff --git a/packages/subject-utils/AGENTS.md b/packages/subject-utils/AGENTS.md index 6b71b2d1a..d7d21c858 100644 --- a/packages/subject-utils/AGENTS.md +++ b/packages/subject-utils/AGENTS.md @@ -1,9 +1,9 @@ # packages/subject-utils -Derives and formats clinical subject identifiers. Nine exports: `generateSubjectHash`, +Derives and formats clinical subject identifiers. Ten exports: `generateSubjectHash`, `encodeScopedSubjectId`, `isSubjectWithPersonalInfo`, `inferSubjectIdentificationMethod`, -`toStoredSubjectId`, `CUSTOM_FIELDS_SUBJECT_ID_PREFIX`, `normalizeCustomFieldValue`, -`deriveCustomFieldsSubjectId`, and `removeSubjectIdScope` (re-exported from +`toStoredSubjectId`, `CUSTOM_FIELDS_SUBJECT_ID_PREFIX`, `DERIVED_SUBJECT_ID_PATTERNS`, +`normalizeCustomFieldValue`, `deriveCustomFieldsSubjectId`, and `removeSubjectIdScope` (re-exported from `@opendatacapture/runtime-internal`). Source-only — `exports` is `"./src/index.ts"`, no build step. Used by `apps/web`, `apps/api` and `packages/react-core`. diff --git a/packages/subject-utils/src/index.ts b/packages/subject-utils/src/index.ts index f08235af6..851a945cc 100644 --- a/packages/subject-utils/src/index.ts +++ b/packages/subject-utils/src/index.ts @@ -9,12 +9,17 @@ import type { SetNonNullable } from 'type-fest'; type SubjectPersonalInfo = Pick; -// libcrypto's sha256 writes each byte as two lowercase hex digits, so no stored name hash has an uppercase letter. -const PERSONAL_INFO_SUBJECT_ID_PATTERN = /^[0-9a-f]{64}$/; - const CUSTOM_FIELDS_SUBJECT_ID_PREFIX = 'cf_'; -const CUSTOM_FIELDS_SUBJECT_ID_PATTERN = new RegExp(`^${CUSTOM_FIELDS_SUBJECT_ID_PREFIX}[0-9a-f]{64}$`); +/** + * The shape of each id derived from what identifies a subject; any other id is a custom id. Checked + * in this order. libcrypto's sha256 writes each byte as two lowercase hex digits, so no stored name + * hash has an uppercase letter. + */ +const DERIVED_SUBJECT_ID_PATTERNS = { + CUSTOM_FIELDS: new RegExp(`^${CUSTOM_FIELDS_SUBJECT_ID_PREFIX}[0-9a-f]{64}$`), + PERSONAL_INFO: /^[0-9a-f]{64}$/ +} as const satisfies { [K in Exclude]: RegExp }; const CUSTOM_FIELDS_SALT_PATTERN = /^[0-9a-f]{64}$/; @@ -92,9 +97,9 @@ export function encodeScopedSubjectId(id: string, options: { groupName: string } } export function inferSubjectIdentificationMethod(subjectId: string): SubjectIdentificationMethod { - if (CUSTOM_FIELDS_SUBJECT_ID_PATTERN.test(subjectId)) { + if (DERIVED_SUBJECT_ID_PATTERNS.CUSTOM_FIELDS.test(subjectId)) { return 'CUSTOM_FIELDS'; - } else if (PERSONAL_INFO_SUBJECT_ID_PATTERN.test(subjectId)) { + } else if (DERIVED_SUBJECT_ID_PATTERNS.PERSONAL_INFO.test(subjectId)) { return 'PERSONAL_INFO'; } return 'CUSTOM_ID'; @@ -146,6 +151,6 @@ export async function deriveCustomFieldsSubjectId( return CUSTOM_FIELDS_SUBJECT_ID_PREFIX + encodeLowercaseHex(derivedBits); } -export { CUSTOM_FIELDS_SUBJECT_ID_PREFIX }; +export { CUSTOM_FIELDS_SUBJECT_ID_PREFIX, DERIVED_SUBJECT_ID_PATTERNS }; export { removeSubjectIdScope } from '@opendatacapture/runtime-internal'; diff --git a/testing/src/pages/_app/admin/settings.page.ts b/testing/src/pages/_app/admin/settings.page.ts index cbbdd0815..855c86bba 100644 --- a/testing/src/pages/_app/admin/settings.page.ts +++ b/testing/src/pages/_app/admin/settings.page.ts @@ -3,7 +3,7 @@ import type { Locator, Page, Response } from '@playwright/test'; import { AppPage } from '../route.page'; -type SettingsTab = 'features' | 'interface' | 'mail'; +type SettingsTab = 'features' | 'interface' | 'mail' | 'subject-identification'; export class AdminSettingsPage extends AppPage { readonly defaultAssignmentDurationInput: Locator; diff --git a/testing/src/specs/custom-fields.spec.ts b/testing/src/specs/custom-fields.spec.ts index 52f54b49a..deb5b4a5e 100644 --- a/testing/src/specs/custom-fields.spec.ts +++ b/testing/src/specs/custom-fields.spec.ts @@ -1,10 +1,13 @@ -import { StartSessionPage } from '../pages/_app/session/start-session.page'; import { expect, test } from '../support/fixtures'; +import type { StartSessionPage } from '../pages/_app/session/start-session.page'; + /** * The definition is one instance-wide document, and it locks for good the first time any subject is * identified with it, so every scenario using it lives in this one serial file. Its first step keeps - * the number of fields the same on every run, which is what a locked definition still accepts. + * the number of fields the same on every run, which is what a locked definition still accepts. Other + * specs start sessions with the built-in methods in parallel, so only custom fields are ever turned + * off here. */ const DEFINITION = { fields: [ @@ -27,8 +30,11 @@ test.describe('custom identifying fields', () => { animalId = `ab${Date.now()}`; }); - test('should define the fields', async ({ api }) => { - const settings = await api.updateSubjectIdentificationSettings({ customFields: DEFINITION }); + test('should define the fields and offer them', async ({ api }) => { + const settings = await api.updateSubjectIdentificationSettings({ + customFields: DEFINITION, + offeredMethods: ['CUSTOM_ID', 'PERSONAL_INFO', 'CUSTOM_FIELDS'] + }); expect(settings.customFields).toMatchObject(DEFINITION); }); @@ -78,4 +84,60 @@ test.describe('custom identifying fields', () => { await identificationForm.getByRole('button', { name: 'Submit' }).click(); await expect(page).toHaveURL(/\/datahub\/subjects\/cf_[0-9a-f]{64}\/table$/); }); + + test.describe('on the settings page', () => { + test.use({ actingRole: 'ADMIN' }); + + test('should show the field list locked once a subject has been identified with it, with its labels still editable', async ({ + getPageModel, + page + }) => { + const settingsPage = await getPageModel('/admin/settings'); + await settingsPage.openTab('subject-identification'); + await expect(page.getByTestId('custom-fields-lock-status')).toHaveAttribute('data-locked', 'true'); + await expect(page.getByTestId('custom-fields-add-field')).toHaveCount(0); + await expect(page.getByTestId('custom-fields-remove')).toHaveCount(0); + await expect(page.getByTestId('custom-field-0-label-en')).toBeEditable(); + }); + + test('should warn how many subjects a built-in method identifies before turning it off', async ({ + getPageModel, + page + }) => { + const settingsPage = await getPageModel('/admin/settings'); + await settingsPage.openTab('subject-identification'); + await page.getByTestId('offered-method-PERSONAL_INFO').click(); + await page.getByTestId('subject-identification-save').click(); + await expect(page.getByTestId('turn-off-count-PERSONAL_INFO')).toHaveText(/^Personal Information: \d+ subjects$/); + // Confirming would stop every other spec from starting a session by personal information. + await page.getByTestId('subject-identification-cancel-save').click(); + }); + + test('should stop offering custom fields in Start Session once they are turned off, and offer them again', async ({ + getPageModel, + page + }) => { + const settingsPage = await getPageModel('/admin/settings'); + await settingsPage.openTab('subject-identification'); + await page.getByTestId('offered-method-CUSTOM_FIELDS').click(); + await page.getByTestId('subject-identification-save').click(); + await expect(page.getByTestId('turn-off-count-CUSTOM_FIELDS')).toHaveText( + /^Animal information: [1-9]\d* subjects$/ + ); + await page.getByTestId('subject-identification-confirm-save').click(); + await expect(page.getByTestId('subject-identification-confirm-dialog')).toBeHidden(); + + const startSessionPage = await getPageModel('/session/start-session'); + await expect(startSessionPage.selectField.locator('option[value="CUSTOM_FIELDS"]')).toHaveCount(0); + + await settingsPage.goto('/admin/settings'); + await settingsPage.openTab('subject-identification'); + await page.getByTestId('offered-method-CUSTOM_FIELDS').click(); + const saved = page.waitForResponse((response) => { + return response.url().endsWith('/v1/subjects/identification/settings') && response.request().method() === 'PUT'; + }); + await page.getByTestId('subject-identification-save').click(); + expect((await saved).ok()).toBe(true); + }); + }); }); From 80a9834a4cac8f0896f0e58821e6a145c00acc93 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Thu, 19 Nov 2026 17:59:05 -0500 Subject: [PATCH 19/19] chore: update route tree --- apps/web/src/route-tree.ts | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/apps/web/src/route-tree.ts b/apps/web/src/route-tree.ts index 9adea1af1..4fa7df2e2 100644 --- a/apps/web/src/route-tree.ts +++ b/apps/web/src/route-tree.ts @@ -19,7 +19,6 @@ import { Route as AppUserRouteImport } from './routes/_app/user' import { Route as AuthLoginRouteImport } from './routes/auth/login' import { Route as AuthResetPasswordRouteImport } from './routes/auth/reset-password' import { Route as AppAdminInstrumentsRouteImport } from './routes/_app/admin/instruments' -import { Route as AppAdminMailRouteImport } from './routes/_app/admin/mail' import { Route as AppAdminSettingsRouteImport } from './routes/_app/admin/settings' import { Route as AppDatahubIndexRouteImport } from './routes/_app/datahub/index' import { Route as AppGroupEmailTemplatesRouteImport } from './routes/_app/group/email-templates' @@ -104,11 +103,6 @@ const AppAdminInstrumentsRoute = AppAdminInstrumentsRouteImport.update({ path: '/admin/instruments', getParentRoute: () => AppRouteRoute, } as any) -const AppAdminMailRoute = AppAdminMailRouteImport.update({ - id: '/admin/mail', - path: '/admin/mail', - getParentRoute: () => AppRouteRoute, -} as any) const AppAdminSettingsRoute = AppAdminSettingsRouteImport.update({ id: '/admin/settings', path: '/admin/settings', @@ -308,7 +302,6 @@ export interface FileRoutesByFullPath { '/auth/login': typeof AuthLoginRoute '/auth/reset-password': typeof AuthResetPasswordRoute '/admin/instruments': typeof AppAdminInstrumentsRoute - '/admin/mail': typeof AppAdminMailRoute '/admin/settings': typeof AppAdminSettingsRoute '/group/email-templates': typeof AppGroupEmailTemplatesRoute '/group/manage': typeof AppGroupManageRoute @@ -354,7 +347,6 @@ export interface FileRoutesByTo { '/auth/reset-password': typeof AuthResetPasswordRoute '/': typeof AppIndexRoute '/admin/instruments': typeof AppAdminInstrumentsRoute - '/admin/mail': typeof AppAdminMailRoute '/admin/settings': typeof AppAdminSettingsRoute '/group/email-templates': typeof AppGroupEmailTemplatesRoute '/group/manage': typeof AppGroupManageRoute @@ -401,7 +393,6 @@ export interface FileRoutesById { '/auth/reset-password': typeof AuthResetPasswordRoute '/_app/': typeof AppIndexRoute '/_app/admin/instruments': typeof AppAdminInstrumentsRoute - '/_app/admin/mail': typeof AppAdminMailRoute '/_app/admin/settings': typeof AppAdminSettingsRoute '/_app/group/email-templates': typeof AppGroupEmailTemplatesRoute '/_app/group/manage': typeof AppGroupManageRoute @@ -449,7 +440,6 @@ export interface FileRouteTypes { | '/auth/login' | '/auth/reset-password' | '/admin/instruments' - | '/admin/mail' | '/admin/settings' | '/group/email-templates' | '/group/manage' @@ -495,7 +485,6 @@ export interface FileRouteTypes { | '/auth/reset-password' | '/' | '/admin/instruments' - | '/admin/mail' | '/admin/settings' | '/group/email-templates' | '/group/manage' @@ -541,7 +530,6 @@ export interface FileRouteTypes { | '/auth/reset-password' | '/_app/' | '/_app/admin/instruments' - | '/_app/admin/mail' | '/_app/admin/settings' | '/_app/group/email-templates' | '/_app/group/manage' @@ -657,13 +645,6 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof AppAdminInstrumentsRouteImport parentRoute: typeof AppRouteRoute } - '/_app/admin/mail': { - id: '/_app/admin/mail' - path: '/admin/mail' - fullPath: '/admin/mail' - preLoaderRoute: typeof AppAdminMailRouteImport - parentRoute: typeof AppRouteRoute - } '/_app/admin/settings': { id: '/_app/admin/settings' path: '/admin/settings' @@ -957,7 +938,6 @@ interface AppRouteRouteChildren { AppUserRoute: typeof AppUserRoute AppIndexRoute: typeof AppIndexRoute AppAdminInstrumentsRoute: typeof AppAdminInstrumentsRoute - AppAdminMailRoute: typeof AppAdminMailRoute AppAdminSettingsRoute: typeof AppAdminSettingsRoute AppGroupEmailTemplatesRoute: typeof AppGroupEmailTemplatesRoute AppGroupManageRoute: typeof AppGroupManageRoute @@ -994,7 +974,6 @@ const AppRouteRouteChildren: AppRouteRouteChildren = { AppUserRoute: AppUserRoute, AppIndexRoute: AppIndexRoute, AppAdminInstrumentsRoute: AppAdminInstrumentsRoute, - AppAdminMailRoute: AppAdminMailRoute, AppAdminSettingsRoute: AppAdminSettingsRoute, AppGroupEmailTemplatesRoute: AppGroupEmailTemplatesRoute, AppGroupManageRoute: AppGroupManageRoute,