/** * Insights tile layout — persisted in `User.insightsLayoutJson`. * * Single source of truth for which insights pills show on `/insights`, * what order they render in, and what the default layout is for new * users. Null / missing column = default layout below; the GET endpoint * never lazy-writes a row, so the column only carries data once the * user has explicitly saved a layout. * * Mirrors `dashboard-layout.ts` for the dashboard widget surface — same * resolver / serializer semantics, same auto-merge of new tile IDs * introduced in later releases. Keeping the two modules structurally * identical means the iOS client + the Settings UI can share rendering * code paths against either surface. */ /** * Every insights tile the layout knows about. Each entry maps to a * routed sub-page under `/insights/` (the mother-page overview * is keyed `"overview"`). The order of entries here is irrelevant — * `DEFAULT_INSIGHTS_LAYOUT.tiles[].order` drives the visual order. * Exported so the API Zod `tileIdEnum` can be built from a single * source of truth. * * v1.8.0 — the canonical ids are English, matching the routed slugs * (`/insights/`) and the naming-convention ADR * (`docs/adr/0001-insights-naming-convention.md`). The ids were German * through v1.7.x and the iOS layout-sync contract * (`GET/PUT /api/insights/layout`) speaks them, so the layout endpoint * keeps ACCEPTING the legacy German ids and NORMALISES them to the * canonical English ones on both read and write — see * `LEGACY_INSIGHTS_TILE_ID_ALIASES` + `normalizeInsightsTileId` below. * No client breaks; iOS migrates to the English ids at its own pace. */ export const INSIGHTS_TILE_IDS = [ "overview", // ── vitals ── "blood-pressure", "pulse", "oxygen", "body-temperature", // ── body composition ── "weight", "bmi", // ── activity ── "active-energy", "workouts", // ── sleep ── "sleep", // ── cardiovascular ── "resting-pulse", "hrv", // ── mood ── "mood", // ── events ── "medications", ] as const; export type InsightsTileId = (typeof INSIGHTS_TILE_IDS)[number]; /** * Legacy (≤ v1.7.x) German tile ids mapped to their canonical English * replacement. The layout endpoint accepts these as input so the iOS * client's stored layouts keep round-tripping after the v1.8.0 rename; * every write path normalises them away before persisting (see * `normalizeInsightsTileId`). `bmi`, `hrv`, `workouts`, and `overview` * were already language-neutral and need no alias. */ export const LEGACY_INSIGHTS_TILE_ID_ALIASES: Record = { blutdruck: "blood-pressure", puls: "pulse", sauerstoff: "oxygen", koerpertemperatur: "body-temperature", gewicht: "weight", "aktive-energie": "active-energy", schlaf: "sleep", ruhepuls: "resting-pulse", stimmung: "mood", medikamente: "medications", }; /** * Every id the layout endpoint accepts on input — canonical English * plus the legacy German aliases. The Zod `tileIdEnum` is built from * this union so a PUT carrying old ids passes validation rather than * tripping a 422; `normalizeInsightsTileId` collapses the union back to * the canonical id before anything persists. */ export const ACCEPTED_INSIGHTS_TILE_IDS = [ ...INSIGHTS_TILE_IDS, ...Object.keys(LEGACY_INSIGHTS_TILE_ID_ALIASES), ] as const; /** * Collapse a legacy German tile id onto its canonical English id. * Canonical ids (and unknown ids) pass through unchanged — the * resolver's known-id filter drops anything truly unrecognised. */ export function normalizeInsightsTileId(id: string): string { return LEGACY_INSIGHTS_TILE_ID_ALIASES[id] ?? id; } export interface InsightsTileConfig { id: InsightsTileId; visible: boolean; order: number; } export interface InsightsLayout { version: number; tiles: InsightsTileConfig[]; } const INSIGHTS_LAYOUT_VERSION = 1; /** * Default layout mirrors the routed tab-strip order — vitals first, * then body composition, activity, sleep, cardiovascular, mood, then * events. Core surfaces are default-visible; the long-tail HealthKit * pills (oxygen saturation, body temperature, active energy, sleep, * resting HR, HRV) stay default-invisible and the user opts in once * the matching data starts to flow. Adding a new tile lands as an * additional `{ id, visible: false, order: N }` row here and the * resolver auto-merges it onto existing users' saved layouts. */ export const DEFAULT_INSIGHTS_LAYOUT: InsightsLayout = { version: INSIGHTS_LAYOUT_VERSION, tiles: [ { id: "overview", visible: true, order: 0 }, { id: "blood-pressure", visible: true, order: 1 }, { id: "pulse", visible: true, order: 2 }, { id: "oxygen", visible: false, order: 3 }, { id: "body-temperature", visible: false, order: 4 }, { id: "weight", visible: true, order: 5 }, { id: "bmi", visible: true, order: 6 }, { id: "active-energy", visible: false, order: 7 }, { id: "workouts", visible: true, order: 8 }, { id: "sleep", visible: false, order: 9 }, { id: "resting-pulse", visible: false, order: 10 }, { id: "hrv", visible: false, order: 11 }, { id: "mood", visible: true, order: 12 }, { id: "medications", visible: true, order: 13 }, ], }; export function resolveInsightsLayout(raw: unknown): InsightsLayout { if (!raw || typeof raw !== "object") return DEFAULT_INSIGHTS_LAYOUT; const candidate = raw as Partial; if ( typeof candidate.version !== "number" || !Array.isArray(candidate.tiles) ) { return DEFAULT_INSIGHTS_LAYOUT; } // v1.8.0 — normalise legacy German tile ids onto their canonical // English replacement BEFORE the known-id filter so a layout persisted // by a ≤ v1.7.x client (or the iOS app still speaking the old ids) // survives the read instead of being silently dropped as "unknown". // Dedupe afterwards: a layout carrying both the legacy and the // canonical id (e.g. a partial migration) keeps the first occurrence // so the round-trip stays idempotent. const knownIds = new Set(INSIGHTS_TILE_IDS); const seen = new Set(); const filtered: InsightsTileConfig[] = candidate.tiles .map((t) => ({ ...t, id: normalizeInsightsTileId(t.id) })) .filter((t): t is InsightsTileConfig => { if (!knownIds.has(t.id) || seen.has(t.id)) return false; seen.add(t.id); return true; }); // Merge with defaults so new tiles introduced in later versions show // up automatically (invisible by default, the user opts in). const savedIds = new Set(filtered.map((t) => t.id)); const missing = DEFAULT_INSIGHTS_LAYOUT.tiles.filter( (t) => !savedIds.has(t.id), ); const maxOrder = Math.max(0, ...filtered.map((t) => t.order)); const appended = missing.map((t, i) => ({ ...t, visible: false, // default-invisible on auto-upgrade order: maxOrder + 1 + i, })); return { version: INSIGHTS_LAYOUT_VERSION, tiles: [...filtered, ...appended].sort((a, b) => a.order - b.order), }; } /** * Input shape for {@link serializeInsightsLayout}. Looser than * {@link InsightsLayout}: the tile `id` is a bare `string` so the PUT * handler can hand a Zod-parsed body that still carries legacy German * aliases — `serializeInsightsLayout` normalises them onto canonical * {@link InsightsTileId} values on the way through. */ export interface InsightsLayoutInput { version: number; tiles: Array<{ id: string; visible: boolean; order: number }>; } export function serializeInsightsLayout( layout: InsightsLayoutInput, ): InsightsLayout { // v1.8.0 — normalise legacy German tile ids onto canonical English // before persisting so the stored blob is always canonical even when // the PUT body carried the old ids (the Zod enum accepts both via // `ACCEPTED_INSIGHTS_TILE_IDS`). Dedupe so a body sending both the // legacy and canonical id for one tile collapses to a single entry, // keeping the dense 0-based order contiguous. const seen = new Set(); return { version: INSIGHTS_LAYOUT_VERSION, tiles: layout.tiles .slice() .sort((a, b) => a.order - b.order) .map((t) => ({ ...t, id: normalizeInsightsTileId(t.id) })) .filter((t) => { if (seen.has(t.id)) return false; seen.add(t.id); return true; }) .map((t, i) => ({ id: t.id as InsightsTileId, visible: t.visible, order: i, // normalize to 0-based dense order })), }; }