@openmrs/esm-report-builder 0.1.1-pre.87

package/src/features/dashboards/utils/dashboard-config.util.test.ts

@@ -0,0 +1,255 @@
+import {
+  DEFAULT_SECTIONS,
+  extractMonitorLayout,
+  normalizeSpan,
+  OTHER_SECTION_KEY,
+  parseDashboardConfig,
+  resolveDashboardLayout,
+  synthesizeEtlDashboardConfig,
+} from './dashboard-config.util';
+import type { ETLMonitorDto } from '../../../types/etl-monitor';
+import type { ReportDto } from '../../../resources/report/reports.api';
+
+function monitor(overrides: Partial<ETLMonitorDto> = {}): ETLMonitorDto {
+  return {
+    uuid: 'm-uuid',
+    name: 'Monitor',
+    displayConfigJson: JSON.stringify({
+      schemaVersion: 2,
+      component: 'TABLE',
+      layout: { section: 'history', span: { sm: 4, md: 8, lg: 16 }, priority: 1 },
+      fields: [],
+    }),
+    ...overrides,
+  } as ETLMonitorDto;
+
+}
+
+function report(overrides: Partial<ReportDto> = {}): ReportDto {
+  return { uuid: 'r-uuid', name: 'Report', ...overrides };
+}
+
+describe('parseDashboardConfig', () => {
+  it('parses a valid v1 config', () => {
+    const config = { schemaVersion: 1 as const, sections: [], widgets: [] };
+    const result = parseDashboardConfig(JSON.stringify(config));
+    expect(result.version).toBe(1);
+    expect(result.config).toEqual(config);
+  });
+
+  it('rejects unparsable JSON', () => {
+    const result = parseDashboardConfig('{oops');
+    expect(result.version).toBe('unknown');
+    expect(result.config).toBeNull();
+    expect(result.error).toBeTruthy();
+  });
+
+  it('rejects unknown schema versions', () => {
+    const result = parseDashboardConfig(JSON.stringify({ schemaVersion: 99 }));
+    expect(result.version).toBe('unknown');
+    expect(result.config).toBeNull();
+  });
+
+  it('treats empty/missing config as unknown', () => {
+    expect(parseDashboardConfig(undefined).version).toBe('unknown');
+    expect(parseDashboardConfig('  ').version).toBe('unknown');
+    expect(parseDashboardConfig(null).config).toBeNull();
+  });
+});
+
+describe('normalizeSpan', () => {
+  it('clamps to breakpoint maxima', () => {
+    expect(normalizeSpan({ sm: 9, md: 20, lg: 32 })).toEqual({ sm: 4, md: 8, lg: 16 });
+  });
+
+  it('fills missing values down the breakpoint chain', () => {
+    expect(normalizeSpan({ sm: 2 })).toEqual({ sm: 2, md: 4, lg: 8 });
+  });
+
+  it('rescues a fully hidden desktop widget', () => {
+    expect(normalizeSpan({ sm: 0, md: 0, lg: 0 }).lg).toBeGreaterThan(0);
+    expect(normalizeSpan({ lg: 0 }, { lg: 12 }).lg).toBe(12);
+  });
+
+  it('uses the default span when none is given', () => {
+    expect(normalizeSpan(undefined)).toEqual({ sm: 4, md: 8, lg: 8 });
+  });
+});
+
+describe('extractMonitorLayout', () => {
+  it('reads layout from a v2 display config', () => {
+    const layout = extractMonitorLayout(monitor());
+    expect(layout.section).toBe('history');
+    expect(layout.span.lg).toBe(16);
+  });
+
+  it('falls back to defaults for unparsable configs', () => {
+    const layout = extractMonitorLayout(monitor({ displayConfigJson: '{bad' }));
+    expect(layout.section).toBe('overview'); // SUMMARY_CARD default
+  });
+
+  it('adapts legacy v1 configs before falling back', () => {
+    const layout = extractMonitorLayout(
+      monitor({
+        monitorType: 'DATA_TABLE' as any,
+        displayConfigJson: JSON.stringify({ columns: [{ key: 'a', header: 'A', jsonPath: '$.a' }] }),
+      }),
+    );
+    // DATA_TABLE adapts to TABLE → history / lg 16
+    expect(layout.section).toBe('history');
+    expect(layout.span.lg).toBe(16);
+  });
+});
+
+describe('resolveDashboardLayout', () => {
+  it('synthesizes an auto-include config for missing/invalid configs', () => {
+    const resolved = resolveDashboardLayout(null, [monitor()], []);
+    expect(resolved.flags.configSynthesized).toBe(true);
+    expect(resolved.sections).toHaveLength(1); // only history has slots
+    expect(resolved.sections[0].key).toBe('history');
+    expect(resolved.etlMonitors).toHaveLength(1);
+  });
+
+  it('auto-includes monitors into their builder-defined sections with their spans', () => {
+    const resolved = resolveDashboardLayout(
+      {
+        schemaVersion: 1,
+        sections: DEFAULT_SECTIONS.map((s) => ({ ...s })),
+        widgets: [],
+        autoInclude: { etlMonitors: { enabled: true } },
+      },
+      [monitor(), monitor({ uuid: 'm2', name: 'Status', displayConfigJson: JSON.stringify({ schemaVersion: 2, component: 'STATUS_CARD', fields: [] }) })],
+      [],
+    );
+    const history = resolved.sections.find((s) => s.key === 'history');
+    const overview = resolved.sections.find((s) => s.key === 'overview');
+    expect(history?.slots).toHaveLength(1);
+    expect(history?.slots[0].span.lg).toBe(16);
+    expect(overview?.slots).toHaveLength(1);
+    expect(overview?.slots[0].explicit).toBe(false);
+  });
+
+  it('explicit widgets win over auto-include (no duplicates, by uuid and by code)', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'overview', label: 'Overview', order: 10 }, { key: 'history', label: 'History', order: 20 }],
+      widgets: [{ widgetType: 'ETL_MONITOR' as const, refUuid: 'm-uuid', sectionKey: 'overview' }],
+      autoInclude: { etlMonitors: { enabled: true } },
+    };
+    const resolved = resolveDashboardLayout(config, [monitor(), monitor({ uuid: 'm2', name: 'Other' })], []);
+    const allEtl = resolved.sections.flatMap((s) => s.slots).filter((s) => s.kind === 'ETL');
+    expect(allEtl.filter((s) => s.monitor?.uuid === 'm-uuid')).toHaveLength(1);
+    expect(allEtl.find((s) => s.monitor?.uuid === 'm-uuid')?.explicit).toBe(true);
+    expect(allEtl.find((s) => s.monitor?.uuid === 'm-uuid')?.sectionKey).toBe('overview');
+  });
+
+  it('dedupes an explicit refCode placement against auto-include', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      widgets: [{ widgetType: 'ETL_MONITOR' as const, refCode: 'mon-code', sectionKey: 'overview' }],
+      autoInclude: { etlMonitors: { enabled: true } },
+    };
+    const resolved = resolveDashboardLayout(config, [monitor({ code: 'mon-code' })], []);
+    const etl = resolved.sections.flatMap((s) => s.slots).filter((s) => s.kind === 'ETL');
+    expect(etl).toHaveLength(1);
+  });
+
+  it('routes unknown section keys into the Other bucket, rendered last', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'overview', label: 'Overview', order: 10 }],
+      widgets: [{ widgetType: 'ETL_MONITOR' as const, refUuid: 'm-uuid', sectionKey: 'nope' }],
+    };
+    const resolved = resolveDashboardLayout(config, [monitor()], []);
+    expect(resolved.sections[resolved.sections.length - 1].key).toBe(OTHER_SECTION_KEY);
+    expect(resolved.sections[resolved.sections.length - 1].slots).toHaveLength(1);
+  });
+
+  it('keeps grid geometry for missing refs (UNAVAILABLE slots)', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'history', label: 'History', order: 10 }],
+      widgets: [{ widgetType: 'ETL_MONITOR' as const, refUuid: 'gone', sectionKey: 'history' }],
+    };
+    const resolved = resolveDashboardLayout(config, [], []);
+    expect(resolved.sections[0].slots[0].status).toBe('UNAVAILABLE');
+    expect(resolved.sections[0].slots[0].unavailableReason).toBe('monitor-missing');
+    expect(resolved.etlMonitors).toHaveLength(0);
+  });
+
+  it('flags unsupported widget types and skips rendering them', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'overview', label: 'Overview', order: 10 }],
+      widgets: [{ widgetType: 'TEXT' } as any],
+    };
+    const resolved = resolveDashboardLayout(config, [], []);
+    expect(resolved.flags.hadUnknownWidgetTypes).toBe(true);
+    expect(resolved.sections[0].slots[0].status).toBe('UNSUPPORTED');
+  });
+
+  it('prunes empty sections unless alwaysShow', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [
+        { key: 'overview', label: 'Overview', order: 10 },
+        { key: 'errors', label: 'Errors', order: 20, alwaysShow: true },
+      ],
+      widgets: [],
+      autoInclude: { etlMonitors: { enabled: false } },
+    };
+    const resolved = resolveDashboardLayout(config, [], []);
+    expect(resolved.sections.map((s) => s.key)).toEqual(['errors']);
+  });
+
+  it('orders slots explicit-first, then by order/priority/title', () => {
+    const autoMonitor = monitor({ uuid: 'auto', name: 'beta auto', displayConfigJson: JSON.stringify({ schemaVersion: 2, component: 'STATUS_CARD', layout: { section: 'overview', span: {}, priority: 5 }, fields: [] }) });
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'overview', label: 'Overview', order: 10 }],
+      widgets: [
+        { widgetType: 'ETL_MONITOR' as const, refUuid: 'm-uuid', sectionKey: 'overview', order: 200, titleOverride: 'second' },
+        { widgetType: 'ETL_MONITOR' as const, refUuid: 'm2', sectionKey: 'overview', order: 100, titleOverride: 'first' },
+      ],
+      autoInclude: { etlMonitors: { enabled: true } },
+    };
+    const resolved = resolveDashboardLayout(config, [monitor(), monitor({ uuid: 'm2', name: 'M2' }), autoMonitor], []);
+    const titles = resolved.sections[0].slots.map((s) => s.title);
+    expect(titles).toEqual(['first', 'second', 'beta auto']);
+  });
+
+  it('computes minRefreshInterval from included ETL monitors, clamped >= 5', () => {
+    const resolved = resolveDashboardLayout(
+      { schemaVersion: 1, widgets: [], autoInclude: { etlMonitors: { enabled: true } } },
+      [monitor({ refreshInterval: 3 }), monitor({ uuid: 'm2', name: 'B', refreshInterval: 60 })],
+      [],
+    );
+    expect(resolved.minRefreshInterval).toBe(5);
+
+    const empty = resolveDashboardLayout({ schemaVersion: 1, widgets: [] }, [], []);
+    expect(empty.minRefreshInterval).toBe(30);
+  });
+
+  it('resolves REPORT widgets, including missing ones', () => {
+    const config = {
+      schemaVersion: 1 as const,
+      sections: [{ key: 'overview', label: 'Overview', order: 10 }],
+      widgets: [
+        { widgetType: 'REPORT' as const, refUuid: 'r-uuid', sectionKey: 'overview' },
+        { widgetType: 'REPORT' as const, refCode: 'gone', sectionKey: 'overview' },
+      ],
+    };
+    const resolved = resolveDashboardLayout(config, [], [report()]);
+    const slots = resolved.sections[0].slots;
+    expect(slots[0].status).toBe('OK');
+    expect(slots[0].report?.name).toBe('Report');
+    expect(slots[1].status).toBe('UNAVAILABLE');
+    expect(slots[1].unavailableReason).toBe('report-missing');
+  });
+
+  it('synthesizeEtlDashboardConfig auto-includes with no explicit widgets', () => {
+    const config = synthesizeEtlDashboardConfig();
+    expect(config.autoInclude?.etlMonitors?.enabled).toBe(true);
+    expect(config.widgets).toHaveLength(0);
+  });
+});

package/src/features/dashboards/utils/dashboard-config.util.ts

@@ -0,0 +1,382 @@
+/**
+ * Dashboard Config Utilities
+ * Parsing, span normalization, monitor-layout extraction and the full
+ * explicit-widgets + auto-include resolution engine for dashboard configs.
+ * Normative behaviour: docs/DASHBOARD_FRONTEND_INSTRUCTIONS.md §3.2.
+ */
+
+import type {
+  DashboardConfigV1,
+  DashboardSectionConfig,
+  ResolvedDashboard,
+  ResolvedDashboardSection,
+  ResolvedWidgetSlot,
+} from '../../../types/dashboard';
+import type { ETLMonitorDto, LayoutMetadata, MonitorComponentType, ResponsiveSpan } from '../../../types/etl-monitor';
+import type { ReportDto } from '../../../resources/report/reports.api';
+import { adaptLegacyConfigToV2, parseDisplayConfig } from '../../../utils/etl-monitor';
+import { getDefaultLayout } from '../../../types/etl-monitor/etl-monitor-v2.types';
+
+export const DASHBOARD_CONFIG_SCHEMA_VERSION = 1;
+
+/** Sections used when the config declares none (and their canonical defaults) */
+export const DEFAULT_SECTIONS: DashboardSectionConfig[] = [
+  { key: 'overview', label: 'Overview', order: 10 },
+  { key: 'execution', label: 'Execution', order: 20 },
+  { key: 'history', label: 'History', order: 30 },
+  { key: 'errors', label: 'Errors', order: 40 },
+  { key: 'configuration', label: 'Configuration & Advanced Settings', order: 50, collapsed: true },
+];
+
+export const DEFAULT_EXPLICIT_SPAN: ResponsiveSpan = { sm: 4, md: 8, lg: 8 };
+
+/** Bucket for widgets/monitors whose section key matches no configured section */
+export const OTHER_SECTION_KEY = '__other';
+
+// ========================
+// Parsing
+// ========================
+
+/**
+ * Parse a dashboard's configJson. Anything other than a valid JSON object
+ * with schemaVersion === 1 is treated as "unknown" — callers synthesize a
+ * fallback config and show a warning banner.
+ */
+export function parseDashboardConfig(
+  configJson?: string | null,
+): { version: 1 | 'unknown'; config: DashboardConfigV1 | null; error?: string } {
+  if (!configJson || !configJson.trim()) {
+    return { version: 'unknown', config: null };
+  }
+  try {
+    const parsed = JSON.parse(configJson);
+    if (parsed && parsed.schemaVersion === DASHBOARD_CONFIG_SCHEMA_VERSION) {
+      return { version: 1, config: parsed as DashboardConfigV1 };
+    }
+    return {
+      version: 'unknown',
+      config: null,
+      error: `Unsupported schemaVersion: ${parsed?.schemaVersion}`,
+    };
+  } catch (e: any) {
+    return { version: 'unknown', config: null, error: e?.message ?? 'Invalid JSON' };
+  }
+}
+
+/**
+ * The fallback config for the ETL dashboard: no explicit sections or
+ * widgets — every active ETL monitor is auto-included by its own layout.
+ */
+export function synthesizeEtlDashboardConfig(): DashboardConfigV1 {
+  return {
+    schemaVersion: 1,
+    sections: [],
+    widgets: [],
+    autoInclude: { etlMonitors: { enabled: true, arrangeBy: 'monitorLayout' } },
+  };
+}
+
+// ========================
+// Spans
+// ========================
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+/**
+ * Clamp a span to the Carbon grid breakpoints (sm 0-4, md 0-8, lg 0-16),
+ * filling missing values from the breakpoint chain and falling back when
+ * a widget would be fully hidden on desktop (lg 0).
+ */
+export function normalizeSpan(span?: ResponsiveSpan, fallback?: ResponsiveSpan): ResponsiveSpan {
+  const fb = fallback ?? DEFAULT_EXPLICIT_SPAN;
+  const raw = span ?? {};
+
+  // Nothing specified at all — the fallback IS the span (e.g. the documented {4,8,8})
+  const hasAny =
+    typeof raw.sm === 'number' || typeof raw.md === 'number' || typeof raw.lg === 'number';
+  if (!hasAny) {
+    return {
+      sm: clamp(fb.sm ?? 4, 0, 4),
+      md: clamp(fb.md ?? 8, 0, 8),
+      lg: clamp(fb.lg ?? 8, 1, 16),
+    };
+  }
+
+  // Partial specification — fill missing breakpoints down the chain
+  const sm = typeof raw.sm === 'number' && Number.isFinite(raw.sm) ? clamp(raw.sm, 0, 4) : 4;
+  const md =
+    typeof raw.md === 'number' && Number.isFinite(raw.md) ? clamp(raw.md, 0, 8) : Math.min(8, sm * 2);
+  let lg =
+    typeof raw.lg === 'number' && Number.isFinite(raw.lg) ? clamp(raw.lg, 0, 16) : Math.min(16, Math.max(md * 2, 4));
+  if (lg === 0) {
+    lg = clamp(fb.lg ?? 8, 1, 16); // never render an invisible widget on desktop
+  }
+  return { sm, md, lg };
+}
+
+// ========================
+// Monitor layout extraction
+// ========================
+
+/**
+ * Resolve a monitor's layout metadata (section/span/priority) from its
+ * displayConfigJson — v2 directly, v1 via the legacy adapter — falling
+ * back to getDefaultLayout for its component type. Single source of
+ * defaults; deliberately NOT extractLayoutMetadata (category heuristics).
+ */
+export function extractMonitorLayout(monitor: ETLMonitorDto): LayoutMetadata {
+  let component: MonitorComponentType | undefined;
+  let layout: LayoutMetadata | undefined;
+
+  try {
+    const parsed = parseDisplayConfig(monitor.displayConfigJson);
+    if (parsed.version === 2 && parsed.config) {
+      component = parsed.config.component;
+      layout = parsed.config.layout;
+    } else {
+      const adapted = adaptLegacyConfigToV2(monitor.displayConfigJson, monitor.monitorType);
+      if (adapted) {
+        component = adapted.component;
+        layout = adapted.layout;
+      }
+    }
+  } catch {
+    // fall through to defaults
+  }
+
+  if (layout && layout.section) {
+    return layout;
+  }
+  return getDefaultLayout(component ?? 'SUMMARY_CARD');
+}
+
+// ========================
+// Resolution engine
+// ========================
+
+function findMonitor(
+  monitors: ETLMonitorDto[],
+  refUuid?: string,
+  refCode?: string,
+): ETLMonitorDto | undefined {
+  if (refUuid) {
+    const byUuid = monitors.find((m) => m.uuid === refUuid);
+    if (byUuid) return byUuid;
+  }
+  if (refCode) {
+    const byCode = monitors.find((m) => m.code === refCode);
+    if (byCode) return byCode;
+  }
+  return undefined;
+}
+
+function findReport(reports: ReportDto[], refUuid?: string, refCode?: string): ReportDto | undefined {
+  if (refUuid) {
+    const byUuid = reports.find((r) => r.uuid === refUuid);
+    if (byUuid) return byUuid;
+  }
+  if (refCode) {
+    const byCode = reports.find((r) => r.code === refCode);
+    if (byCode) return byCode;
+  }
+  return undefined;
+}
+
+/** Explicit before auto; explicit order asc; auto priority asc; then title asc */
+function sortSlots(slots: ResolvedWidgetSlot[]): ResolvedWidgetSlot[] {
+  return [...slots].sort((a, b) => {
+    if (a.explicit !== b.explicit) return a.explicit ? -1 : 1;
+    const explicitDelta = (a.explicitOrder ?? 0) - (b.explicitOrder ?? 0);
+    if (explicitDelta !== 0) return explicitDelta;
+    const priorityDelta = (a.priority ?? 999) - (b.priority ?? 999);
+    if (priorityDelta !== 0) return priorityDelta;
+    return a.title.toLowerCase().localeCompare(b.title.toLowerCase());
+  });
+}
+
+/**
+ * Resolve a dashboard config into renderable sections and slots.
+ *
+ * Step 0 — normalize: null/invalid configs become a synthesized auto-include
+ *          config (flagged via `flags.configSynthesized`).
+ * Step 1 — explicit widgets first, in authoring order; missing refs become
+ *          UNAVAILABLE slots so grid geometry is preserved.
+ * Step 2 — autoInclude: active monitors not already placed (explicit wins,
+ *          deduped on resolved monitor uuid), appended AFTER explicit slots.
+ * Step 3 — unknown section keys bucket into "__other" ("Other", last).
+ * Step 4 — order slots, prune empty sections (unless alwaysShow), collect
+ *          the ETL monitors + min refresh interval for data fetching.
+ */
+export function resolveDashboardLayout(
+  config: DashboardConfigV1 | null,
+  monitors: ETLMonitorDto[],
+  reports: ReportDto[],
+): ResolvedDashboard {
+  const flags = { configSynthesized: false, hadUnknownWidgetTypes: false };
+
+  let effective = config;
+  if (!effective) {
+    effective = synthesizeEtlDashboardConfig();
+    flags.configSynthesized = true;
+  }
+
+  // Sections in display order (explicit order, else 10 * (index + 1); ties by array index)
+  const rawSections = effective.sections?.length
+    ? effective.sections
+    : DEFAULT_SECTIONS.map((s) => ({ ...s }));
+  const orderedSections = rawSections
+    .map((s, i) => ({ s, i }))
+    .sort((a, b) => (a.s.order ?? (a.i + 1) * 10) - (b.s.order ?? (b.i + 1) * 10) || a.i - b.i)
+    .map((x) => x.s);
+
+  const sectionKeys = new Set(orderedSections.map((s) => s.key));
+  const buckets = new Map<string, ResolvedWidgetSlot[]>();
+  const bucketFor = (key: string): ResolvedWidgetSlot[] => {
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(key, bucket);
+    }
+    return bucket;
+  };
+
+  const usedSlotKeys = new Set<string>();
+  const uniqueSlotKey = (base: string): string => {
+    let key = base;
+    let n = 2;
+    while (usedSlotKeys.has(key)) {
+      key = `${base}-${n++}`;
+    }
+    usedSlotKeys.add(key);
+    return key;
+  };
+
+  // Step 1 — explicit widgets
+  const placedMonitors = new Set<string>();
+  (effective.widgets ?? []).forEach((w, idx) => {
+    if (!w || !w.widgetType) return;
+
+    const sectionKey = sectionKeys.has(w.sectionKey) ? w.sectionKey : OTHER_SECTION_KEY;
+    const explicitOrder = w.order ?? (idx + 1) * 100;
+    const span = normalizeSpan(w.span, DEFAULT_EXPLICIT_SPAN);
+    const baseKey = w.key || `${w.widgetType}:${w.refUuid ?? w.refCode ?? idx}`;
+
+    if (w.widgetType === 'ETL_MONITOR') {
+      const monitor = findMonitor(monitors, w.refUuid, w.refCode);
+      if (!monitor) {
+        bucketFor(sectionKey).push({
+          slotKey: uniqueSlotKey(baseKey),
+          status: 'UNAVAILABLE',
+          explicit: true,
+          explicitOrder,
+          title: w.titleOverride ?? w.refCode ?? w.refUuid ?? 'Monitor',
+          sectionKey,
+          span,
+          unavailableReason: 'monitor-missing',
+        });
+        return;
+      }
+      if (monitor.uuid) placedMonitors.add(monitor.uuid);
+      bucketFor(sectionKey).push({
+        slotKey: uniqueSlotKey(baseKey),
+        status: 'OK',
+        kind: 'ETL',
+        explicit: true,
+        explicitOrder,
+        title: w.titleOverride ?? monitor.name,
+        footerLabel: w.footerLabel,
+        sectionKey,
+        span,
+        monitor,
+      });
+    } else if (w.widgetType === 'REPORT') {
+      const report = findReport(reports, w.refUuid, w.refCode);
+      bucketFor(sectionKey).push({
+        slotKey: uniqueSlotKey(baseKey),
+        status: report ? 'OK' : 'UNAVAILABLE',
+        kind: 'REPORT',
+        explicit: true,
+        explicitOrder,
+        title: w.titleOverride ?? report?.name ?? w.refCode ?? w.refUuid ?? 'Report',
+        footerLabel: w.footerLabel,
+        sectionKey,
+        span,
+        report,
+        unavailableReason: report ? undefined : 'report-missing',
+      });
+    } else {
+      flags.hadUnknownWidgetTypes = true;
+      bucketFor(sectionKey).push({
+        slotKey: uniqueSlotKey(baseKey),
+        status: 'UNSUPPORTED',
+        explicit: true,
+        explicitOrder,
+        title: w.titleOverride ?? w.widgetType,
+        sectionKey,
+        span,
+        unsupportedWidgetType: w.widgetType,
+      });
+    }
+  });
+
+  // Step 2 — autoInclude (explicit wins; dedupe on resolved monitor uuid)
+  const autoInclude = effective.autoInclude?.etlMonitors;
+  if (autoInclude?.enabled) {
+    const fallbackSpan = autoInclude.defaultSpan ?? DEFAULT_EXPLICIT_SPAN;
+    const queue = monitors
+      .filter((m) => m.uuid && !placedMonitors.has(m.uuid))
+      .sort(
+        (a, b) =>
+          (a.sortOrder ?? 0) - (b.sortOrder ?? 0) ||
+          (a.name ?? '').toLowerCase().localeCompare((b.name ?? '').toLowerCase()),
+      );
+
+    for (const monitor of queue) {
+      const layout = extractMonitorLayout(monitor);
+      let sectionKey: string | null = null;
+      if (layout.section && sectionKeys.has(layout.section)) {
+        sectionKey = layout.section;
+      } else if (autoInclude.defaultSectionKey && sectionKeys.has(autoInclude.defaultSectionKey)) {
+        sectionKey = autoInclude.defaultSectionKey;
+      }
+      bucketFor(sectionKey ?? OTHER_SECTION_KEY).push({
+        slotKey: uniqueSlotKey(`ETL_MONITOR:${monitor.uuid}`),
+        status: 'OK',
+        kind: 'ETL',
+        explicit: false,
+        priority: layout.priority ?? 999,
+        title: monitor.name,
+        sectionKey: sectionKey ?? OTHER_SECTION_KEY,
+        span: normalizeSpan(layout.span, fallbackSpan),
+        monitor,
+      });
+    }
+  }
+
+  // Step 3 — the "Other" bucket for unknown section keys, rendered last
+  const resolvedSections: ResolvedDashboardSection[] = orderedSections.map((s) => ({
+    ...s,
+    slots: sortSlots(buckets.get(s.key) ?? []),
+  }));
+  const otherSlots = buckets.get(OTHER_SECTION_KEY);
+  if (otherSlots && otherSlots.length > 0) {
+    resolvedSections.push({ key: OTHER_SECTION_KEY, label: 'Other', order: 9999, slots: sortSlots(otherSlots) });
+  }
+
+  // Step 4 — prune empty sections and collect data-fetch inputs
+  const visibleSections = resolvedSections.filter((s) => s.slots.length > 0 || s.alwaysShow === true);
+  const etlMonitors = visibleSections.flatMap((s) =>
+    s.slots.filter((slot) => slot.status === 'OK' && slot.kind === 'ETL' && slot.monitor).map((slot) => slot.monitor!),
+  );
+  const intervals = etlMonitors.map((m) => m.refreshInterval ?? 30);
+  const minRefreshInterval = intervals.length > 0 ? Math.max(5, Math.min(...intervals)) : 30;
+
+  return {
+    sections: visibleSections,
+    etlMonitors,
+    minRefreshInterval,
+    flags,
+  };
+}