/** * v1.5.4 — Medication wizard payload + pure helpers. * * The wizard is a popup that drives the same eight-step decision in * a "one question per breath" cadence. The pure helpers here * (state machine, validation gate, request body builder, summary * formatter) carry the test surface; the dialog and step components * compose them. * * Step encoding: * 1. Name (medication-global) * 2. Treatment class / clinical category (medication-global) * 3. Dose (medication-global) * 4. Course window (medication-global) * 5. Cadence (per-schedule) * 6. Sub-cadence detail (per-schedule, conditional) * 7. Times of day (per-schedule) * 8. Schedule list + reminders + summary (medication-global) * * The visible step counter follows the path the user actually walks * for the ACTIVE schedule: * * ONE_SHOT_PATH = [1, 2, 3, 4, 8] — 5 steps * DAILY_PATH = [1, 2, 3, 4, 5, 7, 8] — 7 steps * RECURRING_PATH = [1, 2, 3, 4, 5, 6, 7, 8] — 8 steps * * The mode is set in Step 5: "Einmalig" picks `oneShot`; every other * radio picks `recurring`. The cadence kind drives the path between * daily (skips Step 6) and the calendar-anchored / rolling shapes. * * Compose-mode: a medication can hold N parallel schedules. Steps 5-7 * mutate the schedule at `activeScheduleIndex`; Step 8 surfaces the * full list with add / edit / remove actions. The flat * `(mode, cadence, subControls, timesOfDay)` fields on the payload * mirror the active draft so the step components stay * single-schedule-aware. The list-mutating helpers below keep that * mirror in sync. * * Each row in Step 2 maps to a `(treatmentClass, category)` pair that * the request body carries. GLP-1-Injektion is the only row that picks * `treatmentClass = "GLP1"`; every other row inherits `GENERIC` and * differs only on the clinical-category bucket the analytics layer * reads. The mapping table is the single source of truth. */ import { encodeCadence } from "@/components/medications/scheduling/CadencePicker"; import { dateToIsoString, isoStringToDate, } from "@/components/medications/scheduling/CourseWindowRow"; import { type CadenceKind, type CadenceSubControls, type CadenceValue, DEFAULT_SUB_CONTROLS, } from "@/components/medications/scheduling/types"; import { inferCadenceFromLegacy, legacyPairFromCadence, } from "@/components/medications/scheduling/legacy-bridge"; import { type MedicationTreatmentClass, type MedicationCategoryValue, type MedicationDeliveryForm, } from "@/lib/validations/medication"; import type { InjectionSiteKey } from "@/lib/medications/injection-sites"; import { isExplicitRange, type DoseWindowEntry, } from "@/components/medications/scheduling/dose-window"; // ──────────────────────────────────────────────────────────────────── // Step 2 — treatment-class taxonomy // ──────────────────────────────────────────────────────────────────── /** * Step 2 row identifiers. Distinct from `MedicationCategoryValue` so a * single picker row can map onto the orthogonal `(treatmentClass, * category)` pair the schema persists. */ export type WizardTreatmentRow = | "bloodPressure" | "diabetes" | "hormone" | "glp1" | "painRelief" | "allergy" | "vitamin" | "supplement" | "antibiotic" | "other"; /** * The ten taxonomy rows in their visible order. Marc-confirmed (D-1 * §3 Step 2): Blutdruck · Diabetes · Hormone · GLP-1-Injektion · * Schmerz · Allergie · Vitamine · Nahrungsergänzung · Antibiotikum · * Sonstiges. */ export const WIZARD_TREATMENT_ROWS: readonly WizardTreatmentRow[] = [ "bloodPressure", "diabetes", "hormone", "glp1", "painRelief", "allergy", "vitamin", "supplement", "antibiotic", "other", ]; /** * Mapping table: Step 2 row → `(treatmentClass, category)` pair the * request body carries. GLP-1 is the only row that bends the Prisma * treatment-class enum; every other row inherits `GENERIC`. */ export const WIZARD_TREATMENT_MAPPING: Record< WizardTreatmentRow, { treatmentClass: MedicationTreatmentClass; category: MedicationCategoryValue } > = { bloodPressure: { treatmentClass: "GENERIC", category: "BLOOD_PRESSURE" }, diabetes: { treatmentClass: "GENERIC", category: "DIABETES" }, hormone: { treatmentClass: "GENERIC", category: "HORMONE" }, glp1: { treatmentClass: "GLP1", category: "OTHER" }, painRelief: { treatmentClass: "GENERIC", category: "PAIN_RELIEF" }, allergy: { treatmentClass: "GENERIC", category: "ALLERGY" }, vitamin: { treatmentClass: "GENERIC", category: "VITAMIN" }, supplement: { treatmentClass: "GENERIC", category: "SUPPLEMENT" }, antibiotic: { treatmentClass: "GENERIC", category: "ANTIBIOTIC" }, other: { treatmentClass: "GENERIC", category: "OTHER" }, }; /** * Reverse-map a `(treatmentClass, category)` pair onto the Step 2 row * the wizard pre-selects on edit. GLP-1 takes priority (a GLP-1 * medication is a GLP-1 row regardless of the side-table value). * Unknown categories fall back to "other". */ export function rowFromTreatment( treatmentClass: string | undefined, category: string | undefined, ): WizardTreatmentRow { if (treatmentClass === "GLP1") return "glp1"; switch (category) { case "BLOOD_PRESSURE": return "bloodPressure"; case "DIABETES": return "diabetes"; case "HORMONE": return "hormone"; case "PAIN_RELIEF": return "painRelief"; case "ALLERGY": return "allergy"; case "VITAMIN": return "vitamin"; case "SUPPLEMENT": return "supplement"; case "ANTIBIOTIC": return "antibiotic"; default: return "other"; } } // ──────────────────────────────────────────────────────────────────── // Wizard payload + per-schedule draft // ──────────────────────────────────────────────────────────────────── /** * One schedule under construction inside the wizard. A medication can * hold N parallel drafts (e.g. short-acting insulin to meals + a * long-acting evening dose on the same medication). The `id` is * present on edit hydrate so the round-trip preserves identity for * the API layer; create drafts leave it undefined. */ export interface ScheduleDraft { id?: string; mode: "oneShot" | "recurring" | null; cadence: CadenceValue; subControls: CadenceSubControls; timesOfDay: string[]; /** * v1.15.18 — per-dose explicit on-time windows. One entry per dose * time the user widened beyond the symmetric ±1h default; a time with * no entry keeps the default band. Empty when every dose uses the * default (the wire then omits / sends `[]`, leaving the column NULL). */ doseWindows?: DoseWindowEntry[]; } /** * The wizard's working state. The cadence + sub-controls mirror the * picker primitives; the treatment row collapses Step 2's * `(treatmentClass, category)` decision into a single value the * mapping table re-expands at submit time. * * Steps 1-4 + 8 are medication-global. Steps 5-7 edit the schedule * at `activeScheduleIndex`. The flat `(mode, cadence, subControls, * timesOfDay)` fields mirror the active draft so the step components * stay single-schedule-aware; the list-mutating helpers below keep * the mirror in sync. */ export interface WizardPayload { name: string; doseAmount: string; doseUnit: string; treatmentRow: WizardTreatmentRow | null; /** * v1.6.0 — route of administration. Drives the injection-site * rotation preview (shown when `INJECTION`) and, paired with * `mode === "oneShot"`, the one-time-injection shape. Defaults to * `ORAL`; the GLP-1 treatment row nudges it to `INJECTION` on * selection so the common case needs no extra tap. */ deliveryForm: MedicationDeliveryForm; /** * v1.6.0 — doses per pen / vial for inventory math. Empty string = * inventory tracking off (maps to `undefined` / NULL on the wire). */ dosesPerUnit: string; /** * v1.8.5 — per-medication injection-site tracking opt-in. Only * surfaced in Step 3 when `deliveryForm === "INJECTION"`. Default * false (opt-in). Toggling it off clears `allowedInjectionSites`. */ trackInjectionSites: boolean; /** * v1.8.5 — per-medication allowed / preferred injection sites. Empty = * no restriction (every site offered). Only meaningful when * `trackInjectionSites` is true. */ allowedInjectionSites: InjectionSiteKey[]; /** Set in Step 5 — mirrors `schedules[activeScheduleIndex].mode`. */ mode: "oneShot" | "recurring" | null; /** Mirrors `schedules[activeScheduleIndex].cadence`. */ cadence: CadenceValue; /** Mirrors `schedules[activeScheduleIndex].subControls`. */ subControls: CadenceSubControls; /** Mirrors `schedules[activeScheduleIndex].timesOfDay`. */ timesOfDay: string[]; /** * v1.15.18 — mirrors `schedules[activeScheduleIndex].doseWindows`. The * per-dose window editor in Step 7 reads + writes this flat slot; the * active-draft helpers keep it in sync with the schedule list. */ doseWindows: DoseWindowEntry[]; startsOn: Date | null; endsOn: Date | null; notificationsEnabled: boolean; /** Every parallel schedule under construction. Always >= 1 entry. */ schedules: ScheduleDraft[]; /** Which schedule Steps 5-7 currently edit. */ activeScheduleIndex: number; } const TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/; function todayUtc(): Date { const now = new Date(); return new Date( Date.UTC(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0, 0), ); } /** Default draft for a fresh schedule slot. */ export function emptyScheduleDraft(): ScheduleDraft { return { mode: null, cadence: encodeCadence("daily", DEFAULT_SUB_CONTROLS), subControls: { ...DEFAULT_SUB_CONTROLS }, timesOfDay: ["08:00"], }; } /** Sensible defaults for a fresh wizard. */ export function emptyWizardPayload(): WizardPayload { const draft = emptyScheduleDraft(); return { name: "", doseAmount: "", doseUnit: "mg", treatmentRow: null, deliveryForm: "ORAL", dosesPerUnit: "", trackInjectionSites: false, allowedInjectionSites: [], mode: draft.mode, cadence: draft.cadence, subControls: draft.subControls, timesOfDay: draft.timesOfDay, doseWindows: draft.doseWindows ?? [], startsOn: todayUtc(), endsOn: null, notificationsEnabled: true, schedules: [draft], activeScheduleIndex: 0, }; } // ──────────────────────────────────────────────────────────────────── // Active-draft mirror helpers // ──────────────────────────────────────────────────────────────────── /** * Project the flat per-schedule fields onto the schedule slot at * `activeScheduleIndex`. Pure — returns a new payload with the * updated schedules array. */ export function commitActiveDraft(payload: WizardPayload): WizardPayload { const idx = payload.activeScheduleIndex; if (idx < 0 || idx >= payload.schedules.length) return payload; const current = payload.schedules[idx]; const next: ScheduleDraft = { ...current, mode: payload.mode, cadence: payload.cadence, subControls: payload.subControls, timesOfDay: payload.timesOfDay, doseWindows: payload.doseWindows, }; const schedules = payload.schedules.slice(); schedules[idx] = next; return { ...payload, schedules }; } /** * Pull the schedule slot at `index` onto the flat mirror fields and * set `activeScheduleIndex`. Used when Step 8 routes the user into a * Bearbeiten action. */ export function setActiveSchedule( payload: WizardPayload, index: number, ): WizardPayload { if (index < 0 || index >= payload.schedules.length) return payload; const draft = payload.schedules[index]; return { ...payload, activeScheduleIndex: index, mode: draft.mode, cadence: draft.cadence, subControls: draft.subControls, timesOfDay: draft.timesOfDay, doseWindows: draft.doseWindows ?? [], }; } /** * Append a fresh empty schedule to the list, commit the currently * active draft so its in-flight edits are not lost, and land the * active pointer on the new slot. */ export function addSchedule(payload: WizardPayload): WizardPayload { const committed = commitActiveDraft(payload); const draft = emptyScheduleDraft(); const schedules = [...committed.schedules, draft]; return { ...committed, schedules, activeScheduleIndex: schedules.length - 1, mode: draft.mode, cadence: draft.cadence, subControls: draft.subControls, timesOfDay: draft.timesOfDay, }; } /** * Remove the schedule at `index`. Refuses when only one schedule * remains — a medication must carry at least one. The active pointer * clamps into the new list bounds and the flat mirror re-syncs. */ export function removeSchedule( payload: WizardPayload, index: number, ): WizardPayload { if (payload.schedules.length <= 1) return payload; if (index < 0 || index >= payload.schedules.length) return payload; const schedules = payload.schedules.filter((_, i) => i !== index); const nextIndex = Math.min(payload.activeScheduleIndex, schedules.length - 1); const draft = schedules[nextIndex]; return { ...payload, schedules, activeScheduleIndex: nextIndex, mode: draft.mode, cadence: draft.cadence, subControls: draft.subControls, timesOfDay: draft.timesOfDay, }; } // ──────────────────────────────────────────────────────────────────── // Path table — visible step counter // ──────────────────────────────────────────────────────────────────── const ONE_SHOT_PATH: readonly number[] = [1, 2, 3, 4, 8]; const DAILY_PATH: readonly number[] = [1, 2, 3, 4, 5, 7, 8]; const RECURRING_PATH: readonly number[] = [1, 2, 3, 4, 5, 6, 7, 8]; /** * The ordered list of raw step numbers for the active mode + cadence. * Mirrors v1.5.3's `progressIndices` shape so the visible counter * tracks the path the user actually walks. * * The mode is set in Step 5. Before that, the wizard renders the * recurring path so the displayed counter stays monotone. */ export function progressIndices( mode: WizardPayload["mode"], cadenceKind: CadenceKind, ): readonly number[] { if (mode === "oneShot") return ONE_SHOT_PATH; if (mode === "recurring" && cadenceKind === "daily") return DAILY_PATH; return RECURRING_PATH; } // ──────────────────────────────────────────────────────────────────── // validateStep — pure per-step gate // ──────────────────────────────────────────────────────────────────── /** * Returns true when the step's required inputs are populated. * * Matrix: * - Step 1: name populated. * - Step 2: treatment row picked. * - Step 3: doseAmount populated. * - Step 4: startsOn present + (endsOn null OR endsOn >= startsOn). * - Step 5: mode picked. * - Step 6: cadence-specific (weekdays >= 1; interval >= 1; monthly * day 1..31; rolling 1..365). * - Step 7: >= 1 valid HH:mm time. * - Step 8: mirrors Step 4 (the reminders toggle has no failure mode). */ export function validateStep(payload: WizardPayload, step: number): boolean { switch (step) { case 1: return payload.name.trim().length > 0; case 2: return payload.treatmentRow !== null; case 3: return payload.doseAmount.trim().length > 0; case 4: if (payload.startsOn === null) return false; if (payload.endsOn === null) return true; return payload.endsOn.getTime() >= payload.startsOn.getTime(); case 5: return payload.mode !== null; case 6: { if (payload.mode !== "recurring") return true; switch (payload.cadence.kind) { case "weekdays": return payload.subControls.weekdays.length >= 1; case "everyNWeeks": return ( payload.subControls.weekdays.length >= 1 && payload.subControls.intervalWeeks >= 1 ); case "monthly": return ( payload.subControls.dayOfMonth >= 1 && payload.subControls.dayOfMonth <= 31 ); case "rolling": return ( payload.subControls.rollingDays >= 1 && payload.subControls.rollingDays <= 365 ); default: return true; } } case 7: { const times = payload.timesOfDay.filter((t) => TIME_RE.test(t)); return times.length >= 1; } case 8: if (payload.startsOn === null) return false; if (payload.endsOn === null) return true; return payload.endsOn.getTime() >= payload.startsOn.getTime(); default: return false; } } // ──────────────────────────────────────────────────────────────────── // firstInvalidIndex — multi-step forward lookahead // ──────────────────────────────────────────────────────────────────── /** * Walks `stepList` from `fromIndex` (inclusive) and returns the index of * the first slot whose `validateStep` gate fails, or `stepList.length` * when every slot from `fromIndex` onward validates. * * This generalises the single-step `canContinue` gate * (`validateStep(payload, step)`) into the forward-jump lookahead the * dot stepper uses: a forward jump to path-index `j` is allowed iff * `firstInvalidIndex(payload, stepList, i) >= j` — i.e. every gate * between the current slot `i` and the target `j` passes. The dot * stepper reuses the same value as its `reachableUntil` ceiling so the * gate and the visual reachability never drift. * * Pure: reuses `validateStep` verbatim, no new validation logic. */ export function firstInvalidIndex( payload: WizardPayload, stepList: readonly number[], fromIndex: number, ): number { for (let k = Math.max(0, fromIndex); k < stepList.length; k++) { if (!validateStep(payload, stepList[k])) return k; } return stepList.length; } // ──────────────────────────────────────────────────────────────────── // buildCreateBody — POST /api/medications request body // ──────────────────────────────────────────────────────────────────── export interface CreateMedicationBody { name: string; dose: string; category: MedicationCategoryValue; treatmentClass: MedicationTreatmentClass; /** v1.6.0 — route of administration (ORAL | INJECTION | OTHER). */ deliveryForm: MedicationDeliveryForm; /** v1.6.0 — doses per pen / vial. Omitted when inventory is off. */ dosesPerUnit?: number; /** v1.8.5 — injection-site tracking opt-in. Omitted for non-injections. */ trackInjectionSites?: boolean; /** v1.8.5 — per-medication allowed sites. Omitted when tracking is off. */ allowedInjectionSites?: InjectionSiteKey[]; /** * v1.5.5 D-3 §10 invariant 16 — the wizard owns the create-time * default for `notificationsEnabled` but never overwrites it on * edit. The detail page's notifications switch is the single source * of truth post-create; the wizard PUT body omits the field so a * user-toggled value never round-trips back to the wizard default. * `buildCreateBody(payload, "edit")` returns `undefined` here. */ notificationsEnabled?: boolean; startsOn?: string; endsOn?: string; oneShot: boolean; schedules: Array<{ id?: string; windowStart: string; windowEnd: string; timesOfDay: string[]; rrule?: string; rollingIntervalDays?: number; daysOfWeek?: number[]; intervalWeeks?: number; /** v1.15.18 — per-dose explicit on-time windows. Omitted when none. */ doseWindows?: DoseWindowEntry[]; }>; } function composeDose(amount: string, unit: string): string { const a = amount.trim(); const u = unit.trim(); if (!a) return u; if (!u) return a; return `${a} ${u}`; } function sortTimes(times: string[]): string[] { return [...times] .filter((t) => TIME_RE.test(t)) .sort((a, b) => a.localeCompare(b)); } function deriveWindow(sortedTimes: string[]): [string, string] { if (sortedTimes.length === 0) return ["08:00", "09:00"]; const start = sortedTimes[0]; if (sortedTimes.length === 1) return [start, addOneHour(start)]; return [start, sortedTimes[sortedTimes.length - 1]]; } function addOneHour(hhmm: string): string { const m = TIME_RE.exec(hhmm); if (!m) return hhmm; const h = Number(m[1]); const mm = m[2]; const next = (h + 1) % 24; return `${String(next).padStart(2, "0")}:${mm}`; } /** * Encode a single `ScheduleDraft` into the request-body schedule * entry. Mirrors the legacy bridge so each schedule dual-writes * `(daysOfWeek, intervalWeeks, rrule, rollingIntervalDays, * timesOfDay)` correctly. The `oneShotMedication` flag suppresses * recurrence on every schedule — the route enforces the * one-schedule-per-one-shot invariant on top. */ export function encodeScheduleDraft( draft: ScheduleDraft, oneShotMedication: boolean, ): CreateMedicationBody["schedules"][number] { const isOneShot = oneShotMedication || draft.mode === "oneShot"; const times = sortTimes( isOneShot ? draft.timesOfDay.slice(0, 1) : draft.timesOfDay, ); const [windowStart, windowEnd] = deriveWindow(times); const legacyPair = legacyPairFromCadence(draft.cadence, draft.subControls); const out: CreateMedicationBody["schedules"][number] = { windowStart, windowEnd, timesOfDay: times, }; if (draft.id) out.id = draft.id; // v1.15.18 — emit only the explicit windows that still name a live dose // time and actually differ from the default ±1h band (a point-equivalent // window leaves the column on the default derivation). if (draft.doseWindows && draft.doseWindows.length > 0) { const liveTimes = new Set(times); const windows = draft.doseWindows.filter( (w) => liveTimes.has(w.timeOfDay) && isExplicitRange(w), ); if (windows.length > 0) out.doseWindows = windows; } if (!isOneShot) { if (draft.cadence.rrule !== null) { out.rrule = draft.cadence.rrule; } else if (draft.cadence.rollingIntervalDays !== null) { out.rollingIntervalDays = draft.cadence.rollingIntervalDays; } if (legacyPair.daysOfWeek.length > 0) { out.daysOfWeek = legacyPair.daysOfWeek; } out.intervalWeeks = legacyPair.intervalWeeks; } return out; } /** * Map a wizard payload onto the `POST /api/medications` body. The * route still requires the legacy `windowStart` / `windowEnd` pair for * the v1.5.x dual-write window; we derive them from the times. * * The treatment row drives both `treatmentClass` and `category` through * the mapping table. The route writes `category` to the side-table. * * Compose-mode: every entry in `payload.schedules` lands in the body's * `schedules` array. The active draft is committed first so any * in-flight edits flow into the encoded entry. * * For one-shot medications the wizard collapses to a single schedule; * recurrence fields are suppressed across the board and the route * normalises `endsOn` to equal `startsOn`. */ export function buildCreateBody( payload: WizardPayload, forMode: "create" | "edit" = "create", ): CreateMedicationBody { const committed = commitActiveDraft(payload); const dose = composeDose(committed.doseAmount, committed.doseUnit); const mapping = committed.treatmentRow !== null ? WIZARD_TREATMENT_MAPPING[committed.treatmentRow] : WIZARD_TREATMENT_MAPPING.other; // A one-shot medication carries exactly one schedule with no // recurrence. We honour the active draft (it carries the times the // user picked); the route enforces the one-schedule invariant. const isOneShot = committed.mode === "oneShot"; const draftsToEmit = isOneShot ? [committed.schedules[committed.activeScheduleIndex] ?? committed.schedules[0]] : committed.schedules; const parsedDosesPerUnit = Number.parseInt(committed.dosesPerUnit, 10); const body: CreateMedicationBody = { name: committed.name.trim(), dose, category: mapping.category, treatmentClass: mapping.treatmentClass, deliveryForm: committed.deliveryForm, ...(Number.isFinite(parsedDosesPerUnit) && parsedDosesPerUnit >= 1 && { dosesPerUnit: parsedDosesPerUnit, }), // v1.8.5 — injection-site tracking is only meaningful for an // INJECTION delivery form. Always send the boolean for an injection // (so edits can deactivate it); send the allowed list only when // tracking is on. Non-injections omit both (server keeps defaults). ...(committed.deliveryForm === "INJECTION" && { trackInjectionSites: committed.trackInjectionSites, ...(committed.trackInjectionSites && { allowedInjectionSites: committed.allowedInjectionSites, }), }), // v1.5.5 D-3 §10 invariant 16 — `notificationsEnabled` only on // create. Edits never round-trip the wizard's default because the // detail page's notifications switch is the single source of // truth post-create. ...(forMode === "create" && { notificationsEnabled: committed.notificationsEnabled, }), oneShot: isOneShot, schedules: draftsToEmit.map((draft) => encodeScheduleDraft(draft, isOneShot)), }; if (committed.startsOn) { body.startsOn = dateToIsoString(committed.startsOn); } if (isOneShot && committed.startsOn) { body.endsOn = dateToIsoString(committed.startsOn); } else if (committed.endsOn) { body.endsOn = dateToIsoString(committed.endsOn); } return body; } // ──────────────────────────────────────────────────────────────────── // summariseCadence — plain-language Step 8 line // ──────────────────────────────────────────────────────────────────── function summaryKeyForDraft( mode: WizardPayload["mode"], cadence: CadenceValue, sub: CadenceSubControls, ): string { if (mode === "oneShot") return "oneShot"; switch (cadence.kind) { case "daily": return "daily"; case "weekdays": return "weekdays"; case "everyNWeeks": return sub.intervalWeeks === 2 ? "biweekly" : "everyNWeeks"; case "monthly": return "monthly"; case "everyNMonths": return sub.intervalMonths === 3 ? "quarterly" : "everyNMonths"; case "yearly": return "yearly"; case "rolling": return "rolling"; case "oneShot": return "oneShot"; } } function weekdaysDetail( tokens: readonly string[], t: (key: string, params?: Record) => string, ): string { if (tokens.length === 0) return ""; const names = tokens .map((tok) => t(`medications.scheduling.cadence.weekdays.long.${tok.toLowerCase()}`), ) .filter(Boolean); if (names.length === 0) return ""; return t("medications.wizard.summary.weekdaysDetail", { days: names.join(", "), }); } /** * The cadence-bearing slice both {@link WizardPayload} and * {@link ScheduleDraft} share. Summary helpers only ever read these three * fields, so the cadence-line builder below stays draft/payload-agnostic. */ type CadenceShape = Pick; /** * The interpolation count the cadence summary keys read. `everyNWeeks` * surfaces the week interval; `rolling` the day interval; everything else * leaves it at zero. Extracted so the medication-wide and per-schedule * summaries can't drift apart. */ function cadenceInterpolationN(shape: CadenceShape): number { if (shape.cadence.kind === "everyNWeeks") return shape.subControls.intervalWeeks; if (shape.cadence.kind === "rolling") return shape.cadence.rollingIntervalDays ?? 0; return 0; } /** * The trailing detail clause appended to a cadence phrase (the weekday * list or the day-of-month). Empty for one-shot doses and for cadences * that carry no extra detail. */ function cadenceDetailPhrase( shape: CadenceShape, t: (key: string, params?: Record) => string, ): string { if (shape.mode === "oneShot") return ""; switch (shape.cadence.kind) { case "weekdays": return weekdaysDetail(shape.subControls.weekdays, t); case "everyNWeeks": return weekdaysDetail(shape.subControls.weekdays, t); case "monthly": return t("medications.wizard.summary.dayOfMonthDetail", { day: shape.subControls.dayOfMonth, }); default: return ""; } } /** * The full cadence line — phrase (`every N weeks`, `daily`, …) plus its * detail clause. Both {@link summariseCadence} and * {@link summariseScheduleDraft} build their first segment from this so * the two summaries render byte-identical cadence text. */ function cadenceLineFor( shape: CadenceShape, t: (key: string, params?: Record) => string, ): string { const cadenceKey = summaryKeyForDraft( shape.mode, shape.cadence, shape.subControls, ); const cadencePhrase = t(`medications.wizard.summary.cadence.${cadenceKey}`, { n: cadenceInterpolationN(shape), }); return cadencePhrase + cadenceDetailPhrase(shape, t); } /** * Plain-language summary for Step 8. Mirrors v1.5.3's helper shape so * the test surface stays familiar. The `t` callback is passed in so * the helper stays pure (no React hook coupling). */ export function summariseCadence( payload: WizardPayload, t: (key: string, params?: Record) => string, ): string { const cadenceLine = cadenceLineFor(payload, t); const timesPhrase = payload.mode !== "oneShot" && payload.timesOfDay.length > 0 ? t("medications.wizard.summary.times", { times: sortTimes(payload.timesOfDay).join(", "), }) : ""; const startPhrase = payload.startsOn ? t("medications.wizard.summary.startsOn", { date: dateToIsoString(payload.startsOn), }) : ""; const endPhrase = payload.mode === "oneShot" ? "" : payload.endsOn ? t("medications.wizard.summary.endsOn", { date: dateToIsoString(payload.endsOn), }) : t("medications.wizard.summary.noEndDate"); return [cadenceLine, timesPhrase, startPhrase, endPhrase] .filter(Boolean) .join(" · "); } /** * Per-schedule summary the Step 8 list cards render. Skips the * course-window phrases (those are medication-global and only need to * render once on the summary block at the top of Step 8). */ export function summariseScheduleDraft( draft: ScheduleDraft, t: (key: string, params?: Record) => string, ): string { const cadenceLine = cadenceLineFor(draft, t); const timesPhrase = draft.mode !== "oneShot" && draft.timesOfDay.length > 0 ? t("medications.wizard.summary.times", { times: sortTimes(draft.timesOfDay).join(", "), }) : ""; return [cadenceLine, timesPhrase].filter(Boolean).join(" · "); } // ──────────────────────────────────────────────────────────────────── // Hydration — edit-path payload from an existing medication // ──────────────────────────────────────────────────────────────────── /** * Snapshot of a medication's persisted state, as the list page passes * it to ``. Schedules carry both * the v1.5 cadence fields and the legacy `(daysOfWeek, intervalWeeks)` * pair so the bridge can hydrate older medications cleanly. */ export interface MedicationPayload { id: string; name: string; dose: string; category: string; treatmentClass?: string; /** v1.6.0 — route of administration. Defaults to ORAL when absent. */ deliveryForm?: string; /** v1.6.0 — doses per pen / vial. NULL = inventory tracking off. */ dosesPerUnit?: number | null; /** v1.8.5 — injection-site tracking opt-in. */ trackInjectionSites?: boolean; /** v1.8.5 — per-medication allowed / preferred injection sites. */ allowedInjectionSites?: string[]; notificationsEnabled: boolean; startsOn: Date | null; endsOn: Date | null; oneShot: boolean; schedules: Array<{ id?: string; windowStart: string; windowEnd: string; label?: string | null; dose?: string | null; daysOfWeek?: number[]; intervalWeeks?: number; timesOfDay?: string[]; rrule?: string | null; rollingIntervalDays?: number | null; /** v1.15.18 — per-dose explicit on-time windows (edit-hydrate). */ doseWindows?: DoseWindowEntry[] | null; }>; } /** Coerce a persisted `deliveryForm` string onto the closed enum. */ function normaliseDeliveryForm(value: string | undefined): MedicationDeliveryForm { return value === "INJECTION" || value === "OTHER" ? value : "ORAL"; } const DOSE_EXPR_RE = /^\s*(\d+(?:[.,]\d+)?)\s*(.*)$/; /** Try to split "5 mg" into ["5", "mg"]; falls back to ["", input]. */ function parseDoseExpression(input: string): { amount: string; unit: string } { const match = DOSE_EXPR_RE.exec(input.trim()); if (!match) return { amount: "", unit: input.trim() }; const amount = match[1] ?? ""; const unit = (match[2] ?? "").trim(); return { amount, unit }; } interface MedicationScheduleSnapshot { id?: string; windowStart: string; windowEnd: string; daysOfWeek?: number[]; intervalWeeks?: number; timesOfDay?: string[]; rrule?: string | null; rollingIntervalDays?: number | null; doseWindows?: DoseWindowEntry[] | null; } function hydrateScheduleDraft( schedule: MedicationScheduleSnapshot, oneShot: boolean, ): ScheduleDraft { const cadence = deriveCadenceFromSchedule(schedule, oneShot); const times = schedule.timesOfDay && schedule.timesOfDay.length > 0 ? [...schedule.timesOfDay] : schedule.windowStart ? [schedule.windowStart] : ["08:00"]; const draft: ScheduleDraft = { mode: oneShot ? "oneShot" : "recurring", cadence: cadence.value, subControls: cadence.subControls, timesOfDay: times, }; if (schedule.id) draft.id = schedule.id; // v1.15.18 — round-trip the persisted per-dose windows so an edit keeps // the user's explicit ranges instead of resetting them to the default. if (schedule.doseWindows && schedule.doseWindows.length > 0) { draft.doseWindows = schedule.doseWindows; } return draft; } /** * Hydrate a `WizardPayload` from a medication snapshot. Every schedule * on the snapshot lands as its own `ScheduleDraft` so compose-mode * surfaces the full list on the edit path. The flat mirror points at * the first draft so the step components stay coherent. * * The legacy bridge (`inferCadenceFromLegacy`) infers a cadence from * the `(daysOfWeek, intervalWeeks)` pair when the v1.5 `rrule` / * `rollingIntervalDays` fields are absent. */ export function hydrateWizardPayload(initial: MedicationPayload): WizardPayload { const base = emptyWizardPayload(); const parsedDose = parseDoseExpression(initial.dose ?? ""); const drafts: ScheduleDraft[] = initial.schedules.length > 0 ? initial.schedules.map((schedule) => hydrateScheduleDraft(schedule, initial.oneShot), ) : [emptyScheduleDraft()]; const first = drafts[0]; return { ...base, name: initial.name ?? "", doseAmount: parsedDose.amount, doseUnit: parsedDose.unit || base.doseUnit, treatmentRow: rowFromTreatment(initial.treatmentClass, initial.category), deliveryForm: normaliseDeliveryForm(initial.deliveryForm), dosesPerUnit: typeof initial.dosesPerUnit === "number" && initial.dosesPerUnit >= 1 ? String(initial.dosesPerUnit) : "", trackInjectionSites: initial.trackInjectionSites ?? false, allowedInjectionSites: (initial.allowedInjectionSites ?? []) as InjectionSiteKey[], mode: first.mode, cadence: first.cadence, subControls: first.subControls, timesOfDay: first.timesOfDay, doseWindows: first.doseWindows ?? [], startsOn: initial.startsOn ?? base.startsOn, endsOn: initial.endsOn, notificationsEnabled: initial.notificationsEnabled ?? true, schedules: drafts, activeScheduleIndex: 0, }; } /** * Decision the dialog uses to pick the landing step on edit-hydrate: * Step 1 for a single-schedule medication (a straight top-down walk), * Step 8 (the summary list) for a multi-schedule one, where the muscle * memory is "see every parallel schedule first". */ export function landingStepForEdit(payload: WizardPayload): number { return payload.schedules.length > 1 ? 8 : 1; } function deriveCadenceFromSchedule( schedule: MedicationPayload["schedules"][number], oneShot: boolean, ): { value: CadenceValue; subControls: CadenceSubControls } { if (oneShot) { const sub = { ...DEFAULT_SUB_CONTROLS }; return { value: encodeCadence("oneShot", sub), subControls: sub }; } if (typeof schedule.rollingIntervalDays === "number") { const sub: CadenceSubControls = { ...DEFAULT_SUB_CONTROLS, rollingDays: schedule.rollingIntervalDays, }; return { value: encodeCadence("rolling", sub), subControls: sub }; } if (typeof schedule.rrule === "string" && schedule.rrule.length > 0) { const sub = subControlsFromRrule(schedule.rrule); const kind = kindFromRrule(schedule.rrule); return { value: encodeCadence(kind, sub), subControls: sub }; } // Legacy fallback — infer from daysOfWeek + intervalWeeks. return inferCadenceFromLegacy({ daysOfWeek: schedule.daysOfWeek ?? [], intervalWeeks: schedule.intervalWeeks ?? 1, }); } function kindFromRrule(rrule: string): CadenceKind { // Lightweight inspection — the picker re-encodes the RRULE on every // change so the wizard never relies on a perfect parse here. if (rrule.includes("FREQ=DAILY")) return "daily"; if (rrule.includes("FREQ=WEEKLY")) { return /INTERVAL=([2-9]|[1-9]\d)/.test(rrule) ? "everyNWeeks" : "weekdays"; } if (rrule.includes("FREQ=MONTHLY")) { return /INTERVAL=([2-9]|[1-9]\d)/.test(rrule) ? "everyNMonths" : "monthly"; } if (rrule.includes("FREQ=YEARLY")) return "yearly"; return "daily"; } function subControlsFromRrule(rrule: string): CadenceSubControls { const sub: CadenceSubControls = { ...DEFAULT_SUB_CONTROLS }; const byday = /BYDAY=([A-Z,]+)/.exec(rrule); if (byday) { const tokens = byday[1].split(",").filter((t) => ["MO", "TU", "WE", "TH", "FR", "SA", "SU"].includes(t), ); if (tokens.length > 0) { sub.weekdays = tokens as CadenceSubControls["weekdays"]; } } const interval = /INTERVAL=(\d{1,3})/.exec(rrule); if (interval) { const n = Number(interval[1]); if (rrule.includes("FREQ=WEEKLY")) sub.intervalWeeks = n; else if (rrule.includes("FREQ=MONTHLY")) sub.intervalMonths = n; } const bymonthday = /BYMONTHDAY=(-?\d{1,2})/.exec(rrule); if (bymonthday) { const n = Number(bymonthday[1]); if (n >= 1 && n <= 31) sub.dayOfMonth = n; } const bymonth = /BYMONTH=(\d{1,2})/.exec(rrule); if (bymonth && bymonthday) { const month = Number(bymonth[1]); const day = Number(bymonthday[1]); if (month >= 1 && month <= 12 && day >= 1 && day <= 31) { sub.yearlyDate = `${new Date().getUTCFullYear()}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`; } } return sub; } // ──────────────────────────────────────────────────────────────────── // Re-exports — convenience for the dialog and tests // ──────────────────────────────────────────────────────────────────── export { dateToIsoString, isoStringToDate };