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

package/src/components/etl-monitor/builder/steps/general-step.component.tsx

@@ -0,0 +1,288 @@
+/**
+ * General Information Step Component
+ * Step 1 of the ETL Monitor Builder
+ *
+ * Fields: Name, Code, Description, Category, Refresh Interval, Timeout, Active
+ */
+
+import React, { useEffect } from 'react';
+import {
+  TextInput,
+  TextArea,
+  NumberInput,
+  Toggle,
+  Select,
+  SelectItem,
+  FormGroup,
+  Stack,
+  InlineNotification,
+} from '@carbon/react';
+import { Information } from '@carbon/icons-react';
+import { useBuilderContext, useUpdateBuilderState } from '../etl-monitor-builder-context';
+import { validateGeneralStep } from '../builder-state-machine';
+import styles from './general-step.scss';
+
+/**
+ * Common category options for ETL monitors
+ */
+const COMMON_CATEGORIES = [
+  { value: 'uganda-etl', label: 'Uganda ETL' },
+  { value: 'etl-status', label: 'ETL Status' },
+  { value: 'data-quality', label: 'Data Quality' },
+  { value: 'system-health', label: 'System Health' },
+  { value: 'performance', label: 'Performance' },
+  { value: 'reporting', label: 'Reporting' },
+  { value: 'custom', label: 'Custom' },
+];
+
+/**
+ * General Information Step Component
+ */
+export default function GeneralStep() {
+  const { state } = useBuilderContext();
+  const updateState = useUpdateBuilderState();
+
+  const { general } = state;
+
+  // Local validation state
+  const [errors, setErrors] = React.useState<Record<string, string>>({});
+  const [touched, setTouched] = React.useState<Record<string, boolean>>({});
+
+  /**
+   * Validate the general configuration
+   */
+  const validateField = (field: string, value: any) => {
+    const fieldErrors: Record<string, string> = {};
+
+    switch (field) {
+      case 'name':
+        if (!value || value.trim() === '') {
+          fieldErrors.name = 'Name is required';
+        }
+        break;
+
+      case 'code':
+        if (!value || value.trim() === '') {
+          fieldErrors.code = 'Code is required';
+        } else if (!/^[a-z0-9-]+$/.test(value)) {
+          fieldErrors.code = 'Code must contain only lowercase letters, numbers, and hyphens';
+        }
+        break;
+
+      case 'refreshInterval':
+        if (value < 5 || value > 3600) {
+          fieldErrors.refreshInterval = 'Refresh interval must be between 5 and 3600 seconds';
+        }
+        break;
+
+      case 'timeout':
+        if (value < 1 || value > 300) {
+          fieldErrors.timeout = 'Timeout must be between 1 and 300 seconds';
+        }
+        break;
+
+      default:
+        break;
+    }
+
+    return fieldErrors;
+  };
+
+  /**
+   * Handle field change
+   */
+  const handleChange = (field: string, value: any) => {
+    const fieldErrors = validateField(field, value);
+    setErrors((prev) => ({ ...prev, ...fieldErrors }));
+    setTouched((prev) => ({ ...prev, [field]: true }));
+
+    updateState({
+      general: { ...general, [field]: value },
+    });
+  };
+
+  /**
+   * Handle category change with label
+   */
+  const handleCategoryChange = (value: string) => {
+    const category = COMMON_CATEGORIES.find((c) => c.value === value);
+    updateState({
+      general: {
+        ...general,
+        category: value,
+        categoryLabel: category?.label || value,
+      },
+    });
+  };
+
+  /**
+   * Generate code from name
+   */
+  const handleNameBlur = () => {
+    if (general.name && (!general.code || general.code === '')) {
+      const generatedCode = general.name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+      handleChange('code', generatedCode);
+    }
+  };
+
+  /**
+   * Validate on mount and when general changes
+   * Memoized to prevent unnecessary effect runs
+   */
+  const validateGeneral = React.useCallback(() => {
+    const validation = validateGeneralStep(general);
+    setErrors(
+      validation.errors.reduce((acc, error) => {
+        const field = error.split(' ')[0].toLowerCase();
+        acc[field] = error;
+        return acc;
+      }, {} as Record<string, string>)
+    );
+  }, [general]);
+
+  useEffect(() => {
+    validateGeneral();
+  }, [validateGeneral]);
+
+  const hasErrors = Object.keys(errors).some((key) => errors[key]);
+
+  return (
+    <div className={styles['general-step']}>
+      {/* Section Header */}
+      <div className={styles['general-step__header']}>
+        <h2>General Information</h2>
+        <p className={styles['general-step__description']}>
+          Define the basic details of your ETL monitor.
+        </p>
+      </div>
+
+      {hasErrors && touched && Object.keys(touched).length > 0 && (
+        <InlineNotification
+          kind="error"
+          title="Validation Errors"
+          subtitle="Please fix the errors below before proceeding"
+          lowContrast
+          style={{ marginBottom: '1rem' }}
+        />
+      )}
+
+      <FormGroup legendText="">
+        <Stack gap={5}>
+          {/* Name */}
+          <TextInput
+            id="monitor-name"
+            labelText="Name *"
+            placeholder="e.g., ETL Module Health"
+            value={general.name}
+            onChange={(e) => handleChange('name', e.target.value)}
+            onBlur={handleNameBlur}
+            invalid={touched.name && !!errors.name}
+            invalidText={errors.name}
+            helperText="A friendly name for this monitor"
+            autoFocus
+          />
+
+          {/* Code */}
+          <TextInput
+            id="monitor-code"
+            labelText="Code *"
+            placeholder="e.g., etl-module-health"
+            value={general.code}
+            onChange={(e) => handleChange('code', e.target.value)}
+            invalid={touched.code && !!errors.code}
+            invalidText={errors.code}
+            helperText="A unique code used to identify this monitor"
+          />
+
+          {/* Description */}
+          <TextArea
+            id="monitor-description"
+            labelText="Description"
+            rows={3}
+            placeholder="Optional description of what this monitor displays"
+            value={general.description}
+            onChange={(e) => handleChange('description', e.target.value)}
+            helperText="Describe what this monitor checks and why it's important"
+          />
+
+          {/* Category */}
+          <Select
+            id="monitor-category"
+            labelText="Category *"
+            value={general.category}
+            onChange={(e) => handleCategoryChange(e.target.value)}
+            helperText="Choose the category this monitor belongs to"
+          >
+            <SelectItem value="" text="Select a category..." />
+            {COMMON_CATEGORIES.map((cat) => (
+              <SelectItem key={cat.value} value={cat.value} text={cat.label} />
+            ))}
+          </Select>
+
+          {/* Active Toggle */}
+          <div className={styles['general-step__toggle']}>
+            <Toggle
+              id="monitor-active"
+              labelText="Active *"
+              labelA="Off"
+              labelB="On"
+              toggled={general.active}
+              onToggle={(checked) => handleChange('active', checked)}
+            />
+            <div className={styles['general-step__toggle-helper']}>
+              Enable or disable this monitor
+            </div>
+          </div>
+
+          {/* Refresh Interval and Timeout */}
+          <Stack orientation="horizontal" gap={5}>
+            <div style={{ flex: 1 }}>
+              <NumberInput
+                id="refresh-interval"
+                label="Refresh Interval (seconds) *"
+                min={5}
+                max={3600}
+                step={5}
+                value={general.refreshInterval}
+                onChange={(event) => {
+                  const val = parseInt((event.target as HTMLInputElement).value) || 30;
+                  handleChange('refreshInterval', val);
+                }}
+                invalid={touched.refreshInterval && !!errors.refreshInterval}
+                invalidText={errors.refreshInterval}
+                helperText="How often the monitor runs"
+              />
+            </div>
+
+            <div style={{ flex: 1 }}>
+              <NumberInput
+                id="timeout"
+                label="Timeout (seconds) *"
+                min={1}
+                max={300}
+                step={1}
+                value={general.timeout}
+                onChange={(event) => {
+                  const val = parseInt((event.target as HTMLInputElement).value) || 10;
+                  handleChange('timeout', val);
+                }}
+                invalid={touched.timeout && !!errors.timeout}
+                invalidText={errors.timeout}
+                helperText="Maximum time to wait for a response"
+              />
+            </div>
+          </Stack>
+        </Stack>
+      </FormGroup>
+
+      {/* Info Banner */}
+      <div className={styles['general-step__info-banner']}>
+        <Information size={16} />
+        <span>You can configure the data source and design in the next steps.</span>
+      </div>
+    </div>
+  );
+}

package/src/components/etl-monitor/builder/steps/general-step.scss

@@ -0,0 +1,103 @@
+/**
+ * General Information Step Styles
+ */
+
+.general-step {
+  padding: 1.5rem;
+
+  &__header {
+    margin-bottom: 2rem;
+
+    h2 {
+      margin: 0 0 0.5rem 0;
+      font-size: 1.25rem;
+      font-weight: 600;
+      color: #111827;
+    }
+  }
+
+  &__description {
+    margin: 0;
+    font-size: 0.875rem;
+    color: #6b7280;
+    line-height: 1.5;
+  }
+
+  &__toggle {
+    padding: 0.5rem 0;
+
+    .cds--toggle__label {
+      font-size: 0.875rem;
+      font-weight: 500;
+    }
+
+    .cds--toggle__text {
+      font-size: 0.8125rem;
+    }
+  }
+
+  &__toggle-helper {
+    margin-top: 0.5rem;
+    font-size: 0.8125rem;
+    color: #6b7280;
+  }
+
+  &__info-banner {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.875rem 1rem;
+    background-color: #eff6ff;
+    border: 1px solid #bfdbfe;
+    border-radius: 0.5rem;
+    margin-top: 1.5rem;
+    color: #1e40af;
+    font-size: 0.875rem;
+
+    svg {
+      flex-shrink: 0;
+    }
+  }
+}
+
+// Dark theme support
+[data-theme='dark'] .general-step {
+  &__header {
+    h2 {
+      color: #f3f4f6;
+    }
+  }
+
+  &__description {
+    color: #9ca3af;
+  }
+
+  &__info-banner {
+    background-color: rgba(30, 64, 175, 0.2);
+    border-color: rgba(59, 130, 246, 0.3);
+    color: #93c5fd;
+  }
+}
+
+// Responsive adjustments
+@media (max-width: 672px) {
+  .general-step {
+    padding: 1rem;
+
+    &__header {
+      h2 {
+        font-size: 1.125rem;
+      }
+    }
+
+    .cds--stack.cds--stack--horizontal {
+      flex-direction: column;
+      gap: 1.5rem !important;
+
+      > div {
+        width: 100% !important;
+        flex: 1 !important;
+      }
+    }
+  }
+}

package/src/components/etl-monitor/builder/steps/index.ts

@@ -0,0 +1,5 @@
+export { default as GeneralStep } from './general-step.component';
+export { default as DataSourceStep } from './data-source-step.component';
+export { default as DesignStep } from './design-step.component';
+export { default as FieldsStep } from './fields-step.component';
+export { default as PreviewStep } from './preview-step.component';

package/src/components/etl-monitor/builder/steps/preview-step.component.tsx

@@ -0,0 +1,245 @@
+/**
+ * Preview & Publish Step Component
+ * Step 5 of the ETL Monitor Builder
+ *
+ * Reference design: docs/image-series-monitor/preview.png (target: stage5)
+ * - Widget preview card with chrome
+ * - Configuration summary (icon + label + value grid)
+ * - Validation checklist
+ * - Save action
+ */
+
+import React, { useMemo, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Button, InlineNotification } from '@carbon/react';
+import {
+  Globe,
+  Renew,
+  Save,
+  Security,
+  View,
+  Timer,
+  Folder,
+  Copy,
+  Checkmark,
+  CheckmarkFilled,
+  Error as ErrorIcon,
+} from '@carbon/icons-react';
+import { useBuilderContext } from '../etl-monitor-builder-context';
+import {
+  stateToSavePayload,
+  validatePreviewStep,
+  getAllValidationErrors,
+} from '../builder-state-machine';
+import { MonitorPreviewRenderer } from '../monitor-preview';
+import { MonitorWidgetCard } from '../../renderers/monitor-widget-card.component';
+import { getDesignConfig } from '../design-registry';
+import styles from './preview-step.scss';
+
+const AUTH_LABELS: Record<string, string> = {
+  NONE: 'None',
+  OPENMRS: 'OpenMRS Session',
+  BASIC: 'Basic Auth',
+  API_KEY: 'API Key',
+  BEARER_TOKEN: 'Bearer Token',
+};
+
+/**
+ * Preview & Publish Step Component
+ */
+export default function PreviewStep() {
+  const { state, saveMonitor } = useBuilderContext();
+  const navigate = useNavigate();
+
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+  const [previewKey, setPreviewKey] = useState(0);
+
+  const savePayload = useMemo(() => stateToSavePayload(state), [state]);
+
+  // Selected design's card identity (accent tile + label, per the
+  // Visualization Cards sheet) reflected above the live widget
+  const design = getDesignConfig(state.componentType);
+
+  const allErrors = useMemo(() => getAllValidationErrors(state), [state]);
+  const previewValidation = useMemo(() => validatePreviewStep(state), [state]);
+  const isReady = allErrors.length === 0 && previewValidation.valid;
+
+  // Status mapping checklist item
+  const statusFields = state.fields.filter((f: any) => f.type === 'STATUS');
+  const statusMapped = statusFields.every((f: any) => (f.statusMappings?.length ?? 0) > 0);
+
+  // Configuration summary items
+  const summaryItems = [
+    { icon: <Globe />, label: 'Data source', value: `${state.endpoint.method} ${state.endpoint.url || '—'}` },
+    { icon: <Security />, label: 'Authentication', value: AUTH_LABELS[state.endpoint.auth?.type] || state.endpoint.auth?.type || 'None' },
+    { icon: <View />, label: 'Component', value: design?.label || state.componentType || '—' },
+    { icon: <Timer />, label: 'Timeout', value: `${state.general.timeout} sec` },
+    { icon: <Renew />, label: 'Refresh', value: `${state.general.refreshInterval} sec` },
+    { icon: <Folder />, label: 'Category', value: state.general.category || '—' },
+  ];
+
+  // Validation checklist
+  const checklist = [
+    {
+      pass: state.testResult ? state.testResult.success : state.mode === 'edit' && !!state.endpoint.url,
+      label: state.testResult ? 'Endpoint tested' : state.mode === 'edit' ? 'Endpoint configured' : 'Endpoint tested',
+      sub: state.testResult
+        ? state.testResult.success
+          ? 'Successfully connected and returned data'
+          : `Test failed: ${state.testResult.error || 'unknown error'}`
+        : state.mode === 'edit'
+          ? 'Endpoint configured and saved previously'
+          : 'Run the endpoint test in the Data Source step',
+    },
+    {
+      pass: state.fields.length > 0,
+      label: 'Fields mapped',
+      sub:
+        state.fields.length > 0
+          ? `${state.fields.length} field${state.fields.length === 1 ? '' : 's'} mapped to response paths`
+          : 'Map at least one response field',
+    },
+    {
+      pass: statusFields.length === 0 || statusMapped,
+      label: 'Status mapping complete',
+      sub:
+        statusFields.length === 0
+          ? 'No status fields configured'
+          : statusMapped
+            ? 'Status and thresholds configured'
+            : 'Add status mappings to all STATUS fields',
+    },
+    {
+      pass: previewValidation.valid,
+      label: 'Preview ready',
+      sub: previewValidation.valid
+        ? 'Monitor preview generated successfully'
+        : 'Fix configuration errors to generate the preview',
+    },
+  ];
+
+  const handleSave = async () => {
+    setSaving(true);
+    setSaveError(null);
+    try {
+      await saveMonitor();
+      navigate('/admin/etl-monitors');
+    } catch (error: any) {
+      setSaveError(error?.message || 'Failed to save monitor');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleCopyJson = async () => {
+    try {
+      await navigator.clipboard.writeText(savePayload.displayConfigJson || '');
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // clipboard unavailable — ignore
+    }
+  };
+
+  return (
+    <div className={styles['preview-step']}>
+      <div className={styles['preview-step__header']}>
+        <h2>Preview &amp; publish</h2>
+        <p className={styles['preview-step__description']}>Review the monitor before saving it to the dashboard.</p>
+      </div>
+
+      {saveError && (
+        <InlineNotification
+          kind="error"
+          lowContrast
+          title="Save Failed"
+          subtitle={saveError}
+          onCloseButtonClick={() => setSaveError(null)}
+          style={{ marginBottom: '1rem' }}
+        />
+      )}
+
+      {/* Widget preview: the selected design's card identity + the exact
+          components and styling the dashboard renders */}
+      <MonitorWidgetCard
+        loading={false}
+        onRefresh={() => setPreviewKey((k) => k + 1)}
+        actions={[{ label: copied ? 'Copied!' : 'Copy configuration JSON', onClick: handleCopyJson }]}
+      >
+        {design && (
+          <div className={styles['preview-design-head']}>
+            <span
+              className={styles['preview-design-head__icon']}
+              style={{ backgroundColor: `${design.accent}1A`, color: design.accent }}
+            >
+              {design.icon}
+            </span>
+            <div className={styles['preview-design-head__text']}>
+              <h3 className={styles['preview-design-head__title']}>{design.label}</h3>
+              <p className={styles['preview-design-head__desc']}>{design.description}</p>
+            </div>
+          </div>
+        )}
+        <div key={previewKey}>
+          <MonitorPreviewRenderer state={state} />
+        </div>
+      </MonitorWidgetCard>
+
+      {/* Configuration summary + validation checklist */}
+      <div className={styles['preview-section']}>
+        <h4>Configuration summary</h4>
+        <div className={styles['preview-summary']}>
+          {summaryItems.map((item) => (
+            <div key={item.label} className={styles['preview-summary__item']}>
+              <span className={styles['preview-summary__icon']}>{item.icon}</span>
+              <div className={styles['preview-summary__text']}>
+                <div className={styles['preview-summary__label']}>{item.label}</div>
+                <div className={styles['preview-summary__value']}>{item.value}</div>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        <div className={styles['preview-section__divider']} />
+
+        <h4>Validation checklist</h4>
+        <div className={styles['preview-checklist']}>
+          {checklist.map((item) => (
+            <div key={item.label} className={styles['preview-checklist__item']}>
+              <span className={[styles['preview-checklist__icon'], item.pass ? styles['preview-checklist__icon--pass'] : styles['preview-checklist__icon--fail']].join(' ')}>
+                {item.pass ? <CheckmarkFilled /> : <ErrorIcon />}
+              </span>
+              <div>
+                <div className={styles['preview-checklist__label']}>{item.label}</div>
+                <div className={styles['preview-checklist__sub']}>{item.sub}</div>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Copy JSON + Save */}
+      <div className={styles['preview-save']}>
+        <Button
+          kind="ghost"
+          size="sm"
+          renderIcon={copied ? Checkmark : Copy}
+          onClick={handleCopyJson}
+        >
+          {copied ? 'Copied!' : 'Copy JSON'}
+        </Button>
+        <Button
+          kind="primary"
+          renderIcon={Save}
+          onClick={handleSave}
+          disabled={saving || !isReady}
+          title={isReady ? undefined : allErrors.join(', ') || 'Configuration incomplete'}
+        >
+          {saving ? 'Saving…' : 'Save Monitor'}
+        </Button>
+      </div>
+    </div>
+  );
+}