feat: add first-attending-day column to roster export

Precompute each person's first attending day (ISO yyyy-mm-dd) at import
time so it flows into the CSV/Excel roster export as a metadata column.

Attendance logic is extracted from the special-needs step into a shared,
framework-agnostic module so the export column and the on-screen day-by-day
table derive from a single per-day presence generator. The specialNeeds
enricher gains a `variant` option (adult/child) driving the computed
firstAttendingDay field; wired up for the staff and staffChildren sources.

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

Author: scriptcoded

packages/backend/config/dataSourceConfig.yml

@@ -58,6 +58,9 @@ dataSources:
       specialNeeds:
         name: jamboree26:specialNeeds
         options:
+          # Adult (funktionär) attendance model: drives the computed
+          # firstAttendingDay export column (se plugins/jamboree26/src/specialNeeds/attendance.ts)
+          variant: adult
           questions:
             # Vilka hela perioder personen önskar delta i (multiselect: Förläger/Lägerperiod/Efterläger) - se plugins/jamboree26/src/specialNeeds
             periodsAttending: "90174"
@@ -129,6 +132,9 @@ dataSources:
       specialNeeds:
         name: jamboree26:specialNeeds
         options:
+          # Child (medföljande barn) attendance model: drives the computed
+          # firstAttendingDay export column (se plugins/jamboree26/src/specialNeeds/attendance.ts)
+          variant: child
           questions:
             # Attendance: single positive multiselect - vilka dagar barnet
             # deltar (inverse of the staff absence model, se variant: child)

plugins/jamboree26/src/enrichers/specialNeeds.test.ts

@@ -280,6 +280,86 @@ describe("jamboree26:specialNeeds enricher", () => {
     expect(result).toEqual({ absenceForlagerDays: [] });
   });
 
+  it("computes firstAttendingDay (yyyy-mm-dd) for the adult variant from the resolved period/absence labels", () => {
+    const result = specialNeeds.enrich(
+      entity(),
+      ctx(
+        {
+          variant: "adult",
+          questions: {
+            periodsAttending: "90174",
+            absenceForlagerDays: "90176",
+          },
+        },
+        {
+          questions: {
+            "90174": ["61759"],
+            "90176": ["61760"],
+          },
+        },
+        {
+          "90174": { "61759": "Förlägret (före 22 juli)" },
+          "90176": { "61760": "Lördag 11 juli" },
+        },
+      ),
+    );
+
+    expect(result).toEqual({
+      periodsAttending: ["Förlägret (före 22 juli)"],
+      absenceForlagerDays: ["Lördag 11 juli"],
+      // 11 juli is absent, so the first attending day is 12 juli.
+      firstAttendingDay: "2026-07-12",
+    });
+  });
+
+  it("computes firstAttendingDay for the child variant from the positive attend-list", () => {
+    const result = specialNeeds.enrich(
+      entity(),
+      ctx(
+        { variant: "child", questions: { attendanceDays: "91058" } },
+        { questions: { "91058": ["61001", "61002"] } },
+        {
+          "91058": {
+            "61001": "Fredag 24 juli",
+            "61002": "Torsdag 23 juli",
+          },
+        },
+      ),
+    );
+
+    expect(result).toEqual({
+      attendanceDays: ["Fredag 24 juli", "Torsdag 23 juli"],
+      firstAttendingDay: "2026-07-23",
+    });
+  });
+
+  it("omits firstAttendingDay when no variant is configured", () => {
+    const result = specialNeeds.enrich(
+      entity(),
+      ctx(
+        { questions: { periodsAttending: "90174" } },
+        { questions: { "90174": ["61759"] } },
+        { "90174": { "61759": "Förlägret (före 22 juli)" } },
+      ),
+    );
+
+    expect(result).toEqual({
+      periodsAttending: ["Förlägret (före 22 juli)"],
+    });
+  });
+
+  it("omits firstAttendingDay when a variant is set but the person attends no day", () => {
+    const result = specialNeeds.enrich(
+      entity(),
+      ctx(
+        { variant: "adult", questions: { periodsAttending: "90174" } },
+        { questions: { "90174": [] } },
+      ),
+    );
+
+    expect(result).toEqual({ periodsAttending: [] });
+  });
+
   it("regression: an unrelated multiselect answer elsewhere in the participant's form must not null out every configured field (real bug - 93% of a real project's participants hit this)", () => {
     const result = specialNeeds.enrich(
       entity(),

plugins/jamboree26/src/enrichers/specialNeeds.ts

@@ -1,17 +1,29 @@
 import type { ImportEnricher } from "@scouterna/scoutin-plugin-api/backend";
 import { type } from "arktype";
+import { firstAttendingDate } from "../specialNeeds/attendance.ts";
 
 // Static per-event config passed via the data source's `enrichWith` entry
 // (object form): a flat map of metadata field name -> Scoutnet registration
 // question ID. Question IDs (and which questions exist at all) are specific
 // to a project's registration form, so they're configured per event rather
-// than hardcoded here. This enricher has no domain knowledge of what the
-// fields mean (diet vs medical vs absence, checkbox vs multiselect vs text) -
-// it just copies each configured question's raw answer under its field name.
-// Grouping/interpreting by field name happens in the jamboree26:specialNeeds
-// step, which is the code contract these field names must match.
+// than hardcoded here. Beyond the single computed `firstAttendingDay` field
+// (below), this enricher has no domain knowledge of what the fields mean (diet
+// vs medical vs absence, checkbox vs multiselect vs text) - it just copies each
+// configured question's raw answer under its field name. Grouping/interpreting
+// by field name happens in the jamboree26:specialNeeds step, which is the code
+// contract these field names must match.
+//
+// `variant` is the one bit of domain config this enricher takes: it selects the
+// attendance model (see ../specialNeeds/attendance.ts) used to derive the single
+// computed `firstAttendingDay` field (an ISO yyyy-mm-dd string). It mirrors the
+// jamboree26:specialNeeds step's own `variant` input - `adult` for the funktionär
+// form's period-gate/absence model, `child` for the "medföljande barn" form's
+// positive attend-list. Omit it and no firstAttendingDay is written (the raw
+// answer fields are still copied as before), so sources with no attendance data
+// (e.g. groups) stay unaffected.
 const Options = type({
   "questions?": type.Record("string", "string"),
+  "variant?": "'adult' | 'child'",
 });
 
 // Structural subset of the raw Scoutnet member record this enricher reads.
@@ -42,6 +54,8 @@ export const specialNeeds: ImportEnricher = {
     const options = Options(ctx.options ?? {});
     const questionMap =
       options instanceof type.errors ? undefined : options.questions;
+    const variant =
+      options instanceof type.errors ? undefined : options.variant;
 
     if (!questionMap || Object.keys(questionMap).length === 0) {
       // No question IDs configured for this event - nothing to enrich, and
@@ -97,6 +111,20 @@ export const specialNeeds: ImportEnricher = {
         result[fieldName] = rawAnswer;
       }
     }
+
+    // Derive the single computed convenience field: the first day this person is
+    // actually attending, as an ISO yyyy-mm-dd string, for the roster export's
+    // "first attending day" column. Uses the just-resolved labels in `result`
+    // (periodsAttending/absence* for adults, attendanceDays for children) so it
+    // needs no separate question config or provider lookup. Only written when a
+    // `variant` is configured and a first day can be determined - otherwise the
+    // key is omitted rather than set to null, keeping it out of the export for
+    // sources with no attendance data.
+    if (variant) {
+      const firstDay = firstAttendingDate(result, variant);
+      if (firstDay != null) result.firstAttendingDay = firstDay;
+    }
+
     return result;
   },
 };

plugins/jamboree26/src/specialNeeds/attendance.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { firstAttendingDate } from "./attendance.ts";
+
+describe("firstAttendingDate (adult)", () => {
+  it("returns the first day of the earliest selected period when no days are marked absent", () => {
+    expect(
+      firstAttendingDate(
+        { periodsAttending: ["Förlägret (före 22 juli)"] },
+        "adult",
+      ),
+    ).toBe("2026-07-11");
+  });
+
+  it("skips days marked absent at the start of an attended period", () => {
+    expect(
+      firstAttendingDate(
+        {
+          periodsAttending: ["Förlägret (före 22 juli)"],
+          absenceForlagerDays: ["Lördag 11 juli", "Söndag 12 juli"],
+        },
+        "adult",
+      ),
+    ).toBe("2026-07-13");
+  });
+
+  it("uses the raw choice ID as a period matcher when the label wasn't resolved", () => {
+    expect(firstAttendingDate({ periodsAttending: ["61760"] }, "adult")).toBe(
+      "2026-07-22",
+    );
+  });
+
+  it("falls through to the next attended period when an earlier one isn't selected", () => {
+    expect(
+      firstAttendingDate(
+        { periodsAttending: ["Post-camp (after August 3)"] },
+        "adult",
+      ),
+    ).toBe("2026-08-03");
+  });
+
+  it("returns an earlier attended period's present day even when a later period is also selected", () => {
+    expect(
+      firstAttendingDate(
+        {
+          periodsAttending: [
+            "Förlägret (före 22 juli)",
+            "Lägerperioden (22 juli - 3 augusti)",
+          ],
+          absenceForlagerDays: ["Lördag 11 juli"],
+        },
+        "adult",
+      ),
+    ).toBe("2026-07-12");
+  });
+
+  it("returns null when no period is selected", () => {
+    expect(firstAttendingDate({}, "adult")).toBeNull();
+    expect(
+      firstAttendingDate({ absenceForlagerDays: ["Lördag 11 juli"] }, "adult"),
+    ).toBeNull();
+  });
+});
+
+describe("firstAttendingDate (child)", () => {
+  it("returns the earliest explicitly attended day", () => {
+    expect(
+      firstAttendingDate(
+        { attendanceDays: ["Torsdag 23 juli", "Fredag 24 juli"] },
+        "child",
+      ),
+    ).toBe("2026-07-23");
+  });
+
+  it("finds the earliest day regardless of answer order", () => {
+    expect(
+      firstAttendingDate(
+        { attendanceDays: ["Fredag 24 juli", "Torsdag 23 juli"] },
+        "child",
+      ),
+    ).toBe("2026-07-23");
+  });
+
+  it("ignores unparseable labels (e.g. an untranslated raw choice ID)", () => {
+    expect(
+      firstAttendingDate(
+        { attendanceDays: ["99999", "Onsdag 5 augusti (inget lägis)"] },
+        "child",
+      ),
+    ).toBe("2026-08-05");
+  });
+
+  it("returns null for an empty or missing attend-list", () => {
+    expect(firstAttendingDate({ attendanceDays: [] }, "child")).toBeNull();
+    expect(firstAttendingDate({}, "child")).toBeNull();
+  });
+});