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

package/src/components/ai-support/ai.types.ts

@@ -0,0 +1,12 @@
+export type AiPromptContext = {
+    page?: string; // e.g. 'Indicators', 'Sections', etc.
+    selectedIndicatorUuids?: string[];
+    activeFilters?: Record<string, any>;
+};
+
+export type AiSuggestion = {
+    title: string;
+    body: string;
+    rawPrompt: string;
+    usedContext: boolean;
+};

package/src/components/app-shell/report-builder-shell.component.tsx

@@ -0,0 +1,242 @@
+import React, { Suspense } from 'react';
+import { Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { InlineLoading } from '@carbon/react';
+import {
+    SideNav,
+    SideNavItems,
+    SideNavLink,
+    SideNavMenu,
+    SideNavMenuItem,
+} from '@carbon/react';
+import type { CarbonIconType } from '@carbon/icons-react';
+import {
+    Home,
+    Report,
+    ChartColumn,
+    Layers,
+    Play,
+    Settings,
+    List,
+    Dashboard,
+    ArrowRight,
+    Folder,
+    DataBase,
+    Task,
+    TableBuilt,
+    Activity,
+} from '@carbon/icons-react';
+
+import { RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
+import styles from './report-builder-shell.scss';
+
+interface NavItem {
+    label: string;
+    path: string;
+    icon?: CarbonIconType;
+    required: string[];
+    /** Extra paths (besides `path`) that mark this item active. */
+    activePaths?: string[];
+}
+
+interface NavSection {
+    /** Sections without a title render their items as top-level links. */
+    title?: string;
+    icon?: CarbonIconType;
+    /** Extra paths that mark this whole section active (e.g. the admin landing). */
+    activePaths?: string[];
+    items: NavItem[];
+}
+
+const NAV: NavSection[] = [
+    {
+        items: [
+            { label: 'Home', path: '/', icon: Home, required: [RB.REPORT_VIEW] },
+            { label: 'Run Reports', path: '/run', icon: Play, required: [RB.REPORT_RUN] },
+            {
+                label: 'Dashboards',
+                path: '/dashboards',
+                icon: Dashboard,
+                required: [RB.DASHBOARD_VIEW],
+            },
+        ],
+    },
+    {
+        title: 'Report Design',
+        icon: Folder,
+        items: [
+            {
+                label: 'Aggregate Reports',
+                path: '/reports',
+                icon: Report,
+                required: [RB.REPORT_VIEW],
+                activePaths: ['/new', '/edit'],
+            },
+            { label: 'Linelist Reports', path: '/linelist', icon: List, required: [RB.REPORT_VIEW] },
+            {
+                label: 'Indicators',
+                path: '/indicators',
+                icon: ChartColumn,
+                required: [RB.INDICATOR_VIEW],
+            },
+            { label: 'Sections', path: '/sections', icon: Layers, required: [RB.SECTION_VIEW] },
+        ],
+    },
+    {
+        title: 'Admin',
+        icon: Settings,
+        activePaths: ['/admin'],
+        items: [
+            {
+                label: 'Import / Export',
+                path: '/import-export',
+                icon: ArrowRight,
+                required: [RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT],
+            },
+            {
+                label: 'Dashboards',
+                path: '/admin/dashboards',
+                required: [RB.DASHBOARD_VIEW],
+            },
+            {
+                label: 'Report Categories',
+                path: '/admin/report-categories',
+                required: [RB.CATEGORY_VIEW],
+            },
+            {
+                label: 'Report Library',
+                path: '/admin/report-library',
+                required: [RB.LIBRARY_VIEW],
+            },
+            { label: 'Data Themes', path: '/admin/themes', required: [RB.THEME_VIEW] },
+            {
+                label: 'Age Categories',
+                path: '/admin/age-categories',
+                required: [RB.AGEGROUP_VIEW],
+            },
+            { label: 'Age Groups', path: '/admin/age-groups', required: [RB.AGEGROUP_VIEW] },
+        ],
+    },
+    {
+        title: 'ETL',
+        icon: DataBase,
+        items: [
+            {
+                label: 'Sources',
+                path: '/admin/etl-sources',
+                icon: DataBase,
+                required: [RB.ETLSOURCE_VIEW],
+            },
+            { label: 'Tasks', path: '/admin/etl-tasks', icon: Task, required: [RB.PACKAGE_IMPORT] },
+            {
+                label: 'Data Browser',
+                path: '/admin/etl-browser',
+                icon: TableBuilt,
+                required: [RB.ETLSOURCE_VIEW],
+            },
+            {
+                label: 'Monitoring',
+                path: '/admin/etl-monitors',
+                icon: Activity,
+                required: [RB.ETLMONITOR_VIEW],
+            },
+        ],
+    },
+];
+
+const ShellSkeleton: React.FC = () => (
+    <div className={styles.shell}>
+        <aside className={styles.leftNav} />
+        <main className={styles.main}>
+            <InlineLoading description="Loading…" />
+        </main>
+    </div>
+);
+
+const ReportBuilderShellInner: React.FC = () => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const { has } = useReportBuilderPrivileges();
+
+    const isActive = (path: string, extraPaths?: string[]) =>
+        location.pathname === path ||
+        location.pathname.startsWith(`${path}/`) ||
+        (extraPaths ?? []).some(
+            (extra) => location.pathname === extra || location.pathname.startsWith(`${extra}/`),
+        );
+
+    const visibleSections = React.useMemo(
+        () =>
+            NAV.map((section) => ({
+                ...section,
+                items: section.items.filter((item) => has(...item.required)),
+            })).filter((section) => section.items.length > 0),
+        [has],
+    );
+
+    return (
+        <div className={styles.shell}>
+            <aside className={styles.leftNav}>
+                <SideNav expanded isPersistent={false} aria-label="Report Builder navigation">
+                    <SideNavItems>
+                        {visibleSections.length === 0 && (
+                            <SideNavMenuItem>
+                                No accessible sections — contact your administrator
+                            </SideNavMenuItem>
+                        )}
+                        {visibleSections.map((section) =>
+                            section.title ? (
+                                <SideNavMenu
+                                    key={section.title}
+                                    renderIcon={section.icon}
+                                    title={section.title}
+                                    isActive={
+                                        section.items.some((item) =>
+                                            isActive(item.path, item.activePaths),
+                                        ) || (section.activePaths ?? []).some((path) => isActive(path))
+                                    }
+                                    defaultExpanded={false}
+                                >
+                                    {section.items.map((item) => (
+                                        <SideNavMenuItem
+                                            key={item.path}
+                                            renderIcon={item.icon}
+                                            isActive={isActive(item.path, item.activePaths)}
+                                            onClick={() => navigate(item.path)}
+                                        >
+                                            {item.label}
+                                        </SideNavMenuItem>
+                                    ))}
+                                </SideNavMenu>
+                            ) : (
+                                section.items.map((item) => (
+                                    <SideNavLink
+                                        key={item.path}
+                                        renderIcon={item.icon}
+                                        isActive={isActive(item.path, item.activePaths)}
+                                        onClick={() => navigate(item.path)}
+                                    >
+                                        {item.label}
+                                    </SideNavLink>
+                                ))
+                            ),
+                        )}
+                    </SideNavItems>
+                </SideNav>
+            </aside>
+
+            <main className={styles.main}>
+                <Outlet />
+            </main>
+        </div>
+    );
+};
+
+/** Session-backed privilege gating suspends on first load — show a skeleton, not a blank page. */
+const ReportBuilderShell: React.FC = () => (
+    <Suspense fallback={<ShellSkeleton />}>
+        <ReportBuilderShellInner />
+    </Suspense>
+);
+
+export default ReportBuilderShell;

package/src/components/app-shell/report-builder-shell.scss

@@ -0,0 +1,18 @@
+.shell {
+  display: grid;
+  grid-template-columns: 280px 1fr;
+  height: 100%;
+  min-height: calc(100vh - 3rem); // keeps it inside O3 header area
+}
+
+.leftNav {
+  border-right: 1px solid var(--cds-border-subtle, #e0e0e0);
+  background: var(--cds-layer-01, #f4f4f4);
+}
+
+.main {
+  /* Vertical scroll only — wide content (e.g. ETL browser tables) must scroll
+     inside its own container (etl-browser gridScroll), never push the shell sideways */
+  overflow-y: auto;
+  overflow-x: hidden;
+}

package/src/components/dashboards/dashboard-config.schema.ts

@@ -0,0 +1,97 @@
+/**
+ * Dashboard config validation helpers
+ * Shared by the dashboard form modal and the raw-JSON editor tab.
+ * Mirrors docs/DASHBOARD_FRONTEND_INSTRUCTIONS.md §3.1 field rules.
+ */
+
+import type { DashboardConfigV1, DashboardSectionConfig, DashboardWidgetConfig } from '../../types/dashboard/dashboard.types';
+import { DEFAULT_SECTIONS } from '../../features/dashboards/utils/dashboard-config.util';
+
+export const SECTION_KEY_PATTERN = /^[a-z0-9][a-z0-9-]{0,49}$/;
+export const CODE_PATTERN = /^[a-z0-9][a-z0-9-]{0,99}$/;
+
+export function createEmptyConfig(): DashboardConfigV1 {
+  return {
+    schemaVersion: 1,
+    sections: DEFAULT_SECTIONS.map((s) => ({ ...s })),
+    widgets: [],
+    autoInclude: { etlMonitors: { enabled: false } },
+  };
+}
+
+export function validateSectionKey(key: string): string | null {
+  if (!key || !key.trim()) return 'Section key is required';
+  if (!SECTION_KEY_PATTERN.test(key)) return 'Section key must be lowercase letters, numbers and dashes (max 50)';
+  return null;
+}
+
+export function validateDashboardConfig(config: DashboardConfigV1): string[] {
+  const errors: string[] = [];
+  const sections = config.sections ?? [];
+
+  const seenKeys = new Set<string>();
+  for (const section of sections) {
+    const keyError = validateSectionKey(section.key);
+    if (keyError) {
+      errors.push(`Section "${section.key || '(blank)'}": ${keyError}`);
+      continue;
+    }
+    if (seenKeys.has(section.key)) {
+      errors.push(`Duplicate section key: "${section.key}"`);
+    }
+    seenKeys.add(section.key);
+    if (!section.label || !section.label.trim()) {
+      errors.push(`Section "${section.key}" is missing a label`);
+    }
+  }
+
+  (config.widgets ?? []).forEach((widget, index) => {
+    const label = widget.titleOverride || widget.refUuid || widget.refCode || `#${index + 1}`;
+    if (!widget.widgetType) {
+      errors.push(`Widget ${label}: widget type is required`);
+    }
+    if (widget.widgetType === 'ETL_MONITOR' || widget.widgetType === 'REPORT') {
+      if (!widget.refUuid && !widget.refCode) {
+        errors.push(`Widget ${label}: provide a UUID or a code reference`);
+      }
+      if (widget.refUuid && widget.refCode) {
+        errors.push(`Widget ${label}: provide only one of UUID or code reference`);
+      }
+    }
+    if (!widget.sectionKey || !seenKeys.has(widget.sectionKey)) {
+      errors.push(`Widget ${label}: assign it to one of the configured sections`);
+    }
+    for (const breakpoint of ['sm', 'md', 'lg'] as const) {
+      const value = widget.span?.[breakpoint];
+      if (value !== undefined && (value < 0 || value > { sm: 4, md: 8, lg: 16 }[breakpoint])) {
+        errors.push(`Widget ${label}: span ${breakpoint} must be 0-${{ sm: 4, md: 8, lg: 16 }[breakpoint]}`);
+      }
+    }
+  });
+
+  return errors;
+}
+
+export interface ParsedDashboardJson {
+  config?: DashboardConfigV1;
+  errors: string[];
+}
+
+export function parseDashboardConfigJson(json: string): ParsedDashboardJson {
+  let parsed: any;
+  try {
+    parsed = JSON.parse(json);
+  } catch (e: any) {
+    return { errors: [`Invalid JSON: ${e?.message ?? 'parse error'}`] };
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return { errors: ['Config must be a JSON object'] };
+  }
+  if (parsed.schemaVersion !== 1) {
+    return { errors: ['schemaVersion must be 1'] };
+  }
+  const config = parsed as DashboardConfigV1;
+  return { config, errors: validateDashboardConfig(config) };
+}
+
+export type { DashboardConfigV1, DashboardSectionConfig, DashboardWidgetConfig };

package/src/components/dashboards/dashboard-form-modal.component.tsx

@@ -0,0 +1,150 @@
+/**
+ * Dashboard Form Modal
+ * Create/edit modal for ReportBuilderDashboard. Owns the basics + the
+ * structured DashboardConfigV1 (sections / widgets / auto-include / raw
+ * JSON tab) and serialises it into configJson on save.
+ */
+
+import React from 'react';
+import { Button, ComposedModal, ModalBody, ModalFooter, ModalHeader } from '@carbon/react';
+import type { DashboardConfigV1, DashboardDto, DashboardType } from '../../types/dashboard/dashboard.types';
+import { parseDashboardConfig } from '../../features/dashboards/utils/dashboard-config.util';
+import { createEmptyConfig, validateDashboardConfig, CODE_PATTERN } from './dashboard-config.schema';
+import DashboardBasicsSection from './sections/dashboard-basics.section';
+import DashboardSectionsEditorSection from './sections/dashboard-sections-editor.section';
+import DashboardWidgetsEditorSection from './sections/dashboard-widgets-editor.section';
+import DashboardAutoIncludeSection from './sections/dashboard-autoinclude.section';
+import DashboardJsonSection from './sections/dashboard-json.section';
+import styles from './dashboards-admin.scss';
+
+export interface DashboardFormState {
+    name: string;
+    code: string;
+    description: string;
+    dashboardType: DashboardType;
+    active: boolean;
+    sortOrder: number;
+    config: DashboardConfigV1;
+}
+
+function stateFromDashboard(dashboard: DashboardDto | null): DashboardFormState {
+    if (!dashboard) {
+        return {
+            name: '',
+            code: '',
+            description: '',
+            dashboardType: 'CUSTOM',
+            active: true,
+            sortOrder: 0,
+            config: createEmptyConfig(),
+        };
+    }
+
+    const parsed = parseDashboardConfig(dashboard.configJson);
+    return {
+        name: dashboard.name ?? '',
+        code: dashboard.code ?? '',
+        description: dashboard.description ?? '',
+        dashboardType: dashboard.dashboardType ?? 'CUSTOM',
+        active: dashboard.active !== false,
+        sortOrder: dashboard.sortOrder ?? 0,
+        config: parsed.config ?? createEmptyConfig(),
+    };
+}
+
+interface DashboardFormModalProps {
+    open: boolean;
+    mode: 'create' | 'edit';
+    initial: DashboardDto | null;
+    onClose: () => void;
+    onSave: (payload: Omit<DashboardDto, 'uuid' | 'retired' | 'dateCreated' | 'dateChanged'>) => Promise<void>;
+}
+
+export default function DashboardFormModal({ open, mode, initial, onClose, onSave }: DashboardFormModalProps) {
+    const [form, setForm] = React.useState<DashboardFormState>(() => stateFromDashboard(initial));
+    const [errors, setErrors] = React.useState<string[]>([]);
+    const [saving, setSaving] = React.useState(false);
+
+    // Re-seed the form each time the modal opens for a different dashboard
+    React.useEffect(() => {
+        if (open) {
+            setForm(stateFromDashboard(initial));
+            setErrors([]);
+            setSaving(false);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, initial?.uuid]);
+
+    const patch = (updates: Partial<DashboardFormState>) => setForm((prev) => ({ ...prev, ...updates }));
+    const patchConfig = (config: DashboardConfigV1) => setForm((prev) => ({ ...prev, config }));
+
+    const validate = (): string[] => {
+        const found: string[] = [];
+        if (!form.name.trim()) found.push('Name is required');
+        if (form.code.trim() && !CODE_PATTERN.test(form.code.trim())) {
+            found.push('Code must be lowercase letters, numbers and dashes');
+        }
+        found.push(...validateDashboardConfig(form.config));
+        return found;
+    };
+
+    const handleSave = async () => {
+        const validation = validate();
+        if (validation.length > 0) {
+            setErrors(validation);
+            return;
+        }
+
+        setSaving(true);
+        setErrors([]);
+        try {
+            await onSave({
+                name: form.name.trim(),
+                code: form.code.trim() || undefined,
+                description: form.description.trim() || undefined,
+                dashboardType: form.dashboardType,
+                active: form.active,
+                sortOrder: form.sortOrder,
+                configJson: JSON.stringify(form.config),
+            });
+        } catch (e: any) {
+            setErrors([e?.message ?? 'Failed to save dashboard']);
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    return (
+        <ComposedModal open={open} onClose={() => !saving && onClose()} size="lg">
+            <ModalHeader
+                title={mode === 'create' ? 'New Dashboard' : 'Edit Dashboard'}
+                label="Dashboards"
+            />
+            <ModalBody hasForm>
+                <div className={styles['dashboard-form-modal__body']}>
+                    {errors.length > 0 && (
+                        <ul className={styles['dashboard-form-modal__errors']}>
+                            {errors.map((error, i) => (
+                                <li key={i}>{error}</li>
+                            ))}
+                        </ul>
+                    )}
+
+                    <DashboardBasicsSection form={form} onChange={patch} />
+                    <DashboardSectionsEditorSection config={form.config} onChange={patchConfig} />
+                    <DashboardWidgetsEditorSection config={form.config} onChange={patchConfig} />
+                    <DashboardAutoIncludeSection config={form.config} onChange={patchConfig} />
+                    <DashboardJsonSection config={form.config} onChange={patchConfig} onErrors={setErrors} />
+                </div>
+            </ModalBody>
+            <ModalFooter onRequestClose={() => !saving && onClose()}>
+                <Button kind="secondary" onClick={() => !saving && onClose()}>
+                    Cancel
+                </Button>
+                <Button kind="primary" onClick={handleSave} disabled={saving}>
+                    {saving ? 'Saving…' : 'Save Dashboard'}
+                </Button>
+            </ModalFooter>
+        </ComposedModal>
+    );
+}

package/src/components/dashboards/dashboards-admin.scss

@@ -0,0 +1,62 @@
+.dashboards-table__actions {
+    display: flex;
+    gap: 0.5rem;
+}
+
+.dashboard-form-modal__body {
+    display: grid;
+    gap: 1.25rem;
+}
+
+.dashboard-form-modal__errors {
+    margin: 0;
+    padding-left: 1rem;
+    color: var(--cds-text-error, #da1e28);
+    font-size: 0.8125rem;
+}
+
+.dashboard-form-modal__errors li {
+    margin-bottom: 0.25rem;
+}
+
+.dashboard-sections-editor__row,
+.dashboard-widgets-editor__row {
+    display: grid;
+    gap: 0.75rem;
+    padding: 0.75rem;
+    border: 1px solid var(--cds-border-subtle, #e0e0e0);
+    border-radius: 0.25rem;
+}
+
+.dashboard-sections-editor__row-fields {
+    display: flex;
+    gap: 0.75rem;
+    align-items: end;
+    flex-wrap: wrap;
+}
+
+.dashboard-widgets-editor__row-fields {
+    display: grid;
+    gap: 0.75rem;
+    grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+}
+
+.dashboard-widgets-editor__span {
+    display: flex;
+    gap: 0.75rem;
+}
+
+.dashboard-editor__hint {
+    font-size: 0.75rem;
+    color: var(--cds-text-secondary, #525252);
+}
+
+.dashboard-json-editor__draft {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.8125rem;
+}
+
+.dashboard-editor__row-actions {
+    display: flex;
+    justify-content: flex-end;
+}