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

package/src/components/admin/etl-browser/etl-browser.component.scss

@@ -0,0 +1,424 @@
+/* ETL Data Browser — three-pane layout + info strip (CSS module) */
+
+.browserGrid {
+  display: flex;
+  gap: 0;
+  align-items: stretch;
+  /* Bounded height so the side panes scroll internally instead of stretching the page */
+  height: calc(100vh - 16rem);
+  min-height: 30rem;
+  /* Flex item of the page Stack: without an explicit floor reset, min-content width
+     (driven by wide preview tables) would inflate this row and the shell with it */
+  min-width: 0;
+  max-width: 100%;
+}
+
+/* Width-controlled wrapper for the draggable/collapsible panes */
+.paneWrap {
+  display: flex;
+  flex-shrink: 0;
+  min-width: 48px;
+  overflow: hidden;
+  transition: width 0.2s ease;
+}
+
+.pane {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+  overflow: hidden;
+  background: var(--cds-layer, #fff);
+  border: 1px solid var(--cds-border-subtle, #dcdcdc);
+  border-radius: 4px;
+}
+
+/* The detail pane is not wrapped — it takes the remaining width.
+   flex-basis 0 + min-width 0 so wide table content can never inflate it
+   (and with it the whole browser row) */
+.detailPane {
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+/* Drag handles between panes (linelist workspace pattern) */
+.resizeHandle {
+  position: relative;
+  z-index: 10;
+  flex-shrink: 0;
+  width: 6px;
+  cursor: col-resize;
+  background-color: transparent;
+  transition: background-color 0.15s ease;
+
+  &::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background-color: transparent;
+    transition: background-color 0.15s ease;
+  }
+
+  &:hover::before,
+  &:active::before {
+    background-color: var(--cds-link-primary, #007d79);
+    opacity: 0.35;
+  }
+
+  &:active {
+    background-color: var(--cds-link-primary, #007d79);
+  }
+}
+
+.paneHeader {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--cds-border-subtle, #dcdcdc);
+}
+
+.paneTitle {
+  font-size: 1rem;
+  font-weight: 600;
+  color: var(--cds-text-primary, #161616);
+}
+
+.paneActions {
+  display: inline-flex;
+  gap: 0.375rem;
+  align-items: center;
+}
+
+.paneSearch {
+  flex-shrink: 0;
+  padding: 0.5rem 0.75rem;
+}
+
+.paneBody {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 0.25rem 0.5rem 0.75rem;
+}
+
+.iconAction {
+  padding: 0.25rem 0.375rem;
+  border: none;
+  background: none;
+  font-size: 0.75rem;
+  color: var(--cds-text-secondary, #525252);
+  cursor: pointer;
+
+  &:hover {
+    color: var(--cds-text-primary, #161616);
+  }
+}
+
+/* Sources + tables lists */
+.sourceList,
+.tableList {
+  display: grid;
+  gap: 0.125rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.sourceRow {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.4375rem 0.5rem;
+  border: none;
+  border-radius: 3px;
+  background: none;
+  font-size: 0.8125rem;
+  color: var(--cds-text-primary, #161616);
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    background: var(--cds-layer-hover, #e8e8e8);
+  }
+}
+
+.sourceRowSelected,
+.sourceRowSelected:hover {
+  background: #e5f6f4;
+  color: var(--cds-link-primary, #007d79);
+  font-weight: 600;
+  box-shadow: inset 3px 0 0 var(--cds-link-primary, #007d79);
+}
+
+.sourceRowIcon {
+  flex-shrink: 0;
+  color: var(--cds-text-secondary, #525252);
+}
+
+.sourceRowName {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.treeEmpty {
+  margin: 0.5rem 0.25rem;
+  font-size: 0.75rem;
+  color: var(--cds-text-secondary, #525252);
+}
+
+/* Tables list */
+.tableRow {
+  display: flex;
+  width: 100%;
+  align-items: flex-start;
+  gap: 0.5rem;
+  padding: 0.5rem;
+  border: none;
+  border-radius: 3px;
+  background: none;
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    background: var(--cds-layer-hover, #e8e8e8);
+  }
+}
+
+.tableRowSelected,
+.tableRowSelected:hover {
+  background: #e5f6f4;
+  box-shadow: inset 3px 0 0 var(--cds-link-primary, #007d79);
+}
+
+.tableRowIcon {
+  flex-shrink: 0;
+  color: var(--cds-text-secondary, #525252);
+}
+
+.tableRowText {
+  display: grid;
+  gap: 0.125rem;
+  min-width: 0;
+}
+
+.tableName {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--cds-text-primary, #161616);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tableMeta {
+  font-size: 0.6875rem;
+  color: var(--cds-text-secondary, #525252);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Detail pane */
+.detailHeader {
+  display: flex;
+  flex-shrink: 0;
+  align-items: flex-start;
+  gap: 0.75rem;
+  padding: 0.875rem 1rem;
+  border-bottom: 1px solid var(--cds-border-subtle, #dcdcdc);
+}
+
+.detailIcon {
+  color: var(--cds-link-primary, #007d79);
+}
+
+.detailHeaderText {
+  flex: 1;
+  min-width: 0;
+}
+
+.detailTitle {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--cds-text-primary, #161616);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.detailMeta {
+  margin: 0.25rem 0 0;
+  font-size: 0.6875rem;
+  color: var(--cds-text-secondary, #525252);
+  white-space: pre-wrap;
+}
+
+.detailActions {
+  display: inline-flex;
+  flex-shrink: 0;
+  gap: 0.5rem;
+}
+
+.detailBody {
+  flex: 1;
+  min-height: 0;
+  padding: 0.75rem 1rem 1rem;
+  /* Vertical scroll only — horizontal overflow belongs to .gridScroll below */
+  overflow-y: auto;
+  overflow-x: hidden;
+}
+
+/* Toolbar (preview + tabs) */
+.toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.25rem 0 0.75rem;
+}
+
+.toolbarSpacer {
+  flex: 1;
+}
+
+.rowSearch {
+  width: 240px;
+}
+
+.truncateNote {
+  margin: 0 0 0.5rem;
+  font-size: 0.6875rem;
+  font-style: italic;
+  color: var(--cds-text-secondary, #525252);
+}
+
+/* Preview grid — the ONLY element that scrolls horizontally */
+.gridScroll {
+  width: 100%;
+  max-width: 100%;
+  max-height: min(60vh, 34rem);
+  overflow-x: auto;
+  overflow-y: auto;
+  border: 1px solid var(--cds-border-subtle, #dcdcdc);
+
+  /* Keep columns at natural width so wide tables scroll inside this container */
+  table {
+    min-width: max-content;
+    table-layout: auto;
+  }
+
+  th {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: var(--cds-layer, #fff);
+  }
+}
+
+/* Shared empty state */
+.emptyState {
+  display: grid;
+  justify-items: center;
+  padding: 2.5rem 2rem;
+  margin: 0.5rem 0;
+  text-align: center;
+  gap: 0.5rem;
+
+  h5 {
+    margin: 0.25rem 0 0;
+  }
+
+  p {
+    margin: 0;
+    max-width: 26rem;
+    font-size: 0.8125rem;
+    color: var(--cds-text-secondary, #525252);
+  }
+
+  code {
+    font-family: monospace;
+  }
+}
+
+/* Metadata tab */
+.metadataFacts {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 1rem;
+  padding: 1rem;
+  background: var(--cds-layer, #fff);
+  border: 1px solid var(--cds-border-subtle, #dcdcdc);
+  border-radius: 4px;
+}
+
+.metadataHeading {
+  margin: 1rem 0 0.5rem;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--cds-text-primary, #161616);
+}
+
+.metadataTypes {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+}
+
+/* Table information strip (rendered inside the detail pane) */
+.infoStrip {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 1rem;
+  margin-top: 0.75rem;
+  padding: 0.875rem 1rem;
+  background: var(--cds-layer, #fff);
+  border: 1px solid var(--cds-border-subtle, #dcdcdc);
+  border-radius: 4px;
+}
+
+.infoCell {
+  display: grid;
+  gap: 0.125rem;
+  min-width: 0;
+}
+
+.infoLabel {
+  font-size: 0.625rem;
+  color: var(--cds-text-secondary, #525252);
+}
+
+.infoValue {
+  font-size: 0.75rem;
+  color: var(--cds-text-primary, #161616);
+  overflow-wrap: anywhere;
+}
+
+/* Responsive: stack panes on narrow windows; drag handles are meaningless vertically */
+@media (max-width: 67rem) {
+  .browserGrid {
+    flex-direction: column;
+    gap: 1rem;
+    height: auto;
+  }
+
+  .paneWrap {
+    width: 100% !important;
+    max-height: 20rem;
+  }
+
+  .resizeHandle {
+    display: none;
+  }
+
+  .detailPane {
+    min-height: 28rem;
+  }
+}

package/src/components/admin/etl-browser/metadata-tab.component.tsx

@@ -0,0 +1,65 @@
+/**
+ * Metadata tab — known facts about the table plus a column-type breakdown.
+ */
+
+import React from 'react';
+import { Tag } from '@carbon/react';
+import type { SchemaTable } from '../../../resources/theme/etl-schema.api';
+import type { TableColumn } from '../../../resources/theme/etl-table-meta.api';
+import { summarizeColumns } from '../../../utils/etl-browser';
+import { formatRelativeTime } from '../../../utils/etl-monitor/value-formatters.util';
+import type { DetailSource } from './table-detail.component';
+import styles from './etl-browser.component.scss';
+
+interface MetadataTabProps {
+    table: SchemaTable;
+    source?: DetailSource;
+    columns: TableColumn[];
+}
+
+function formatRows(rows?: number | null): string {
+    return typeof rows === 'number' ? `${rows.toLocaleString()} (approximate)` : '—';
+}
+
+function formatFreshness(updateTime?: string | null): string {
+    return updateTime ? formatRelativeTime(updateTime, { pastOnly: true }) : '—';
+}
+
+export default function MetadataTab({ table, source, columns }: MetadataTabProps) {
+    const summary = summarizeColumns(columns);
+
+    const facts: Array<{ label: string; value: string }> = [
+        { label: 'Source', value: source?.name ?? '—' },
+        { label: 'Schema', value: source?.schemaName ?? '—' },
+        { label: 'Type', value: table.tableType === 'VIEW' ? 'View' : 'Table' },
+        { label: 'Rows', value: formatRows(table.rows) },
+        { label: 'Last refreshed', value: formatFreshness(table.updateTime) },
+        { label: 'Columns', value: columns.length ? String(columns.length) : '—' },
+    ];
+
+    return (
+        <div>
+            <div className={styles.metadataFacts}>
+                {facts.map((fact) => (
+                    <div key={fact.label} className={styles.infoCell}>
+                        <span className={styles.infoLabel}>{fact.label}</span>
+                        <span className={styles.infoValue}>{fact.value}</span>
+                    </div>
+                ))}
+            </div>
+
+            <h6 className={styles.metadataHeading}>Column types</h6>
+            {summary.byType.length === 0 ? (
+                <p className={styles.truncateNote}>Column metadata not loaded yet.</p>
+            ) : (
+                <div className={styles.metadataTypes}>
+                    {summary.byType.map((entry) => (
+                        <Tag key={entry.type} size="sm" type="cool-gray">
+                            {entry.type}: {entry.count}
+                        </Tag>
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/components/admin/etl-browser/preview-grid.component.tsx

@@ -0,0 +1,189 @@
+/**
+ * Data tab — preview grid over the fetched ≤1000-row sample.
+ * Search spans all fetched rows; pagination is client-side.
+ */
+
+import React, { useEffect, useMemo, useState } from 'react';
+import {
+  Button,
+  DataTable,
+  InlineLoading,
+  InlineNotification,
+  Pagination,
+  Search,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+  Tile,
+} from '@carbon/react';
+import { Renew } from '@carbon/react/icons';
+import type { SqlPreviewResponse } from '../../../resources/preview/sql-preview.api';
+import { downloadCsv } from '../../../utils/etl-browser';
+import styles from './etl-browser.component.scss';
+
+const PREVIEW_ROW_CAP = 1000;
+const PAGE_SIZES = [10, 25, 50, 100];
+
+interface PreviewGridProps {
+    table: string;
+    data?: SqlPreviewResponse;
+    loading: boolean;
+    error?: string;
+    onRefresh: () => void;
+}
+
+export default function PreviewGrid({ table, data, loading, error, onRefresh }: PreviewGridProps) {
+    const [rowSearch, setRowSearch] = useState('');
+    const [currentPage, setCurrentPage] = useState(1);
+    const [pageSize, setPageSize] = useState(10);
+
+    useEffect(() => {
+        setRowSearch('');
+        setCurrentPage(1);
+    }, [table, data]);
+
+    const filtered = useMemo(() => {
+        if (!data) return [];
+        const query = rowSearch.trim().toLowerCase();
+        if (!query) return data.rows;
+        return data.rows.filter((row) => row.some((cell) => String(cell ?? '').toLowerCase().includes(query)));
+    }, [data, rowSearch]);
+
+    const totalPages = Math.max(1, Math.ceil(filtered.length / pageSize));
+    const safePage = Math.min(currentPage, totalPages);
+    const startIndex = (safePage - 1) * pageSize;
+    const pageRows = filtered.slice(startIndex, startIndex + pageSize);
+    const showTruncatedNote = Boolean(data && (data.truncated || data.rows.length >= PREVIEW_ROW_CAP));
+
+    const headers = (data?.columns ?? []).map((column) => ({ key: column, header: column }));
+    const rows: Array<Record<string, any> & { id: string }> = pageRows.map((row, index) => {
+        const mapped: Record<string, any> & { id: string } = { id: String(startIndex + index) };
+        data?.columns.forEach((column, columnIndex) => {
+            const value = row[columnIndex];
+            mapped[column] = value === null || value === undefined ? '' : String(value);
+        });
+        return mapped;
+    });
+
+    if (loading) {
+        return <InlineLoading description={`Loading preview of ${table}...`} />;
+    }
+
+    if (error) {
+        return (
+            <div>
+                <InlineNotification
+                    lowContrast
+                    kind="error"
+                    title="Preview failed"
+                    subtitle={error}
+                />
+                <div className={styles.toolbar}>
+                    <Button kind="secondary" size="sm" renderIcon={Renew} onClick={onRefresh}>
+                        Retry
+                    </Button>
+                </div>
+                <p className={styles.truncateNote}>
+                    Preview needs the &quot;sql.execute&quot; privilege and a valid table name.
+                </p>
+            </div>
+        );
+    }
+
+    if (!data) {
+        return null;
+    }
+
+    return (
+        <div>
+            <div className={styles.toolbar}>
+                <Search
+                    size="sm"
+                    className={styles.rowSearch}
+                    placeholder="Search rows..."
+                    labelText="Search rows"
+                    value={rowSearch}
+                    onChange={(e) => setRowSearch((e as React.ChangeEvent<HTMLInputElement>).target.value)}
+                />
+                <Tag size="sm" type="cool-gray">
+                    {data.rowCount.toLocaleString()} rows in preview
+                </Tag>
+                <span className={styles.toolbarSpacer} />
+                <Button kind="secondary" size="sm" renderIcon={Renew} onClick={onRefresh}>
+                    Refresh
+                </Button>
+                <Button
+                    kind="tertiary"
+                    size="sm"
+                    onClick={() => downloadCsv(`${table}-preview`, data.columns, data.rows)}
+                    disabled={data.rows.length === 0}>
+                    Export CSV
+                </Button>
+            </div>
+
+            {showTruncatedNote && (
+                <p className={styles.truncateNote}>
+                    Preview shows the first {PREVIEW_ROW_CAP.toLocaleString()} rows — use the search or export to
+                    work with more.
+                </p>
+            )}
+
+            {data.rows.length === 0 ? (
+                <Tile className={styles.emptyState}>
+                    <h5>This table has no rows</h5>
+                    <p>The table may be empty, or it is a view that currently returns no rows.</p>
+                </Tile>
+            ) : (
+                <>
+                    <DataTable rows={rows} headers={headers} size="sm" isSortable>
+                        {({
+                            rows: tableRows,
+                            headers: tableHeaders,
+                            getHeaderProps,
+                            getRowProps,
+                            getTableProps,
+                        }) => (
+                            <TableContainer className={styles.gridScroll}>
+                                <Table {...getTableProps()} useZebraStyles>
+                                    <TableHead>
+                                        <TableRow>
+                                            {tableHeaders.map((header) => (
+                                                <TableHeader key={header.key} {...getHeaderProps({ header })}>
+                                                    {header.header}
+                                                </TableHeader>
+                                            ))}
+                                        </TableRow>
+                                    </TableHead>
+                                    <TableBody>
+                                        {tableRows.map((row) => (
+                                            <TableRow key={row.id} {...getRowProps({ row })}>
+                                                {row.cells.map((cell) => (
+                                                    <TableCell key={cell.id}>{cell.value}</TableCell>
+                                                ))}
+                                            </TableRow>
+                                        ))}
+                                    </TableBody>
+                                </Table>
+                            </TableContainer>
+                        )}
+                    </DataTable>
+                    <Pagination
+                        page={safePage}
+                        pageSize={pageSize}
+                        pageSizes={PAGE_SIZES}
+                        totalItems={filtered.length}
+                        onChange={({ page, pageSize: newSize }) => {
+                            setPageSize(newSize);
+                            setCurrentPage(page);
+                        }}
+                    />
+                </>
+            )}
+        </div>
+    );
+}

package/src/components/admin/etl-browser/relationships-tab.component.tsx

@@ -0,0 +1,21 @@
+/**
+ * Relationships tab — honest empty state: the report builder API does not
+ * expose foreign-key metadata for ETL tables.
+ */
+
+import React from 'react';
+import { Information } from '@carbon/react/icons';
+import styles from './etl-browser.component.scss';
+
+export default function RelationshipsTab() {
+    return (
+        <div className={styles.emptyState}>
+            <Information size={28} />
+            <h5>Relationships aren&apos;t available yet</h5>
+            <p>
+                The report builder API doesn&apos;t expose foreign-key metadata for ETL tables. Column-level hints
+                (e.g. columns ending in <code>_id</code>) may still be visible in the Columns tab.
+            </p>
+        </div>
+    );
+}