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

package/src/components/admin/etl-browser/sources-tree.component.tsx

@@ -0,0 +1,118 @@
+/**
+ * Sources tree — selectable ETL source groups. Clicking a source scopes the
+ * Tables pane to it; tables themselves are browsed in the middle pane.
+ */
+
+import React from 'react';
+import { Button, InlineLoading, InlineNotification, Search, Tag } from '@carbon/react';
+import { CaretLeft, CaretRight, DataBase } from '@carbon/react/icons';
+import classNames from 'classnames';
+import type { TableGroup } from '../../../utils/etl-browser';
+import styles from './etl-browser.component.scss';
+
+interface SourcesTreeProps {
+    groups: TableGroup[];
+    /** Unmatched tables; rendered as its own group only when non-empty */
+    other: TableGroup;
+    selectedSourceId: string;
+    searchValue: string;
+    loading: boolean;
+    error: string | null;
+    /** Panel collapsed to a slim strip (linelist workspace pattern) */
+    collapsed?: boolean;
+    onToggleCollapsed?: () => void;
+    onSearchChange: (value: string) => void;
+    onSelectSource: (sourceId: string) => void;
+}
+
+export default function SourcesTree({
+    groups,
+    other,
+    selectedSourceId,
+    searchValue,
+    loading,
+    error,
+    collapsed = false,
+    onToggleCollapsed,
+    onSearchChange,
+    onSelectSource,
+}: SourcesTreeProps) {
+    const query = searchValue.trim().toLowerCase();
+    const all: TableGroup[] = [...groups, ...(other.tables.length > 0 ? [other] : [])];
+    const visible = query ? all.filter((group) => group.name.toLowerCase().includes(query)) : all;
+
+    return (
+        <div className={styles.pane}>
+            <div className={styles.paneHeader}>
+                {!collapsed && (
+                    <>
+                        <span className={styles.paneTitle}>Data Sources</span>
+                        <span className={styles.paneActions}>
+                            {onToggleCollapsed && (
+                                <Button
+                                    kind="ghost"
+                                    size="sm"
+                                    hasIconOnly
+                                    renderIcon={CaretLeft}
+                                    iconDescription="Collapse panel"
+                                    onClick={onToggleCollapsed}
+                                />
+                            )}
+                        </span>
+                    </>
+                )}
+                {collapsed && onToggleCollapsed && (
+                    <Button
+                        kind="ghost"
+                        size="sm"
+                        hasIconOnly
+                        renderIcon={CaretRight}
+                        iconDescription="Expand panel"
+                        onClick={onToggleCollapsed}
+                    />
+                )}
+            </div>
+            {!collapsed && (
+                <>
+                    <div className={styles.paneSearch}>
+                        <Search
+                            size="sm"
+                            placeholder="Search sources..."
+                            labelText="Search sources"
+                            value={searchValue}
+                            onChange={(e) => onSearchChange((e as React.ChangeEvent<HTMLInputElement>).target.value)}
+                        />
+                    </div>
+                    <div className={styles.paneBody}>
+                        {loading && <InlineLoading description="Loading sources..." />}
+                        {error && <InlineNotification lowContrast kind="error" title="Error" subtitle={error} />}
+                        {!loading && !error && visible.length === 0 && <p className={styles.treeEmpty}>No sources match</p>}
+                        {visible.length > 0 && (
+                            <ul className={styles.sourceList}>
+                                {visible.map((group) => (
+                                    <li key={group.id}>
+                                        <button
+                                            type="button"
+                                            className={classNames(
+                                                styles.sourceRow,
+                                                selectedSourceId === group.id && styles.sourceRowSelected,
+                                            )}
+                                            onClick={() => onSelectSource(group.id)}>
+                                            <span className={styles.sourceRowIcon}>
+                                                <DataBase size={16} />
+                                            </span>
+                                            <span className={styles.sourceRowName}>{group.name}</span>
+                                            <Tag size="sm" type="gray">
+                                                {group.tables.length}
+                                            </Tag>
+                                        </button>
+                                    </li>
+                                ))}
+                            </ul>
+                        )}
+                    </div>
+                </>
+            )}
+        </div>
+    );
+}

package/src/components/admin/etl-browser/table-detail.component.tsx

@@ -0,0 +1,124 @@
+/**
+ * Detail pane — table header, meta line, actions and the four detail tabs
+ * (Data / Columns / Metadata / Relationships).
+ */
+
+import React from 'react';
+import { Button, Tab, TabList, TabPanel, TabPanels, Tabs, Tile } from '@carbon/react';
+import { Renew, TableBuilt } from '@carbon/react/icons';
+import type { SchemaTable } from '../../../resources/theme/etl-schema.api';
+import type { TableColumn } from '../../../resources/theme/etl-table-meta.api';
+import { formatRelativeTime } from '../../../utils/etl-monitor/value-formatters.util';
+import ColumnsTab from './columns-tab.component';
+import MetadataTab from './metadata-tab.component';
+import PreviewGrid from './preview-grid.component';
+import RelationshipsTab from './relationships-tab.component';
+import TableInfoStrip from './table-info-strip.component';
+import { useTablePreview } from './use-table-preview';
+import styles from './etl-browser.component.scss';
+
+export type DetailTab = 'data' | 'columns' | 'metadata' | 'relationships';
+
+/** Minimal source facts the detail pane needs (satisfied by a TableGroup) */
+export type DetailSource = { name?: string; schemaName?: string };
+
+interface TableDetailProps {
+    table: SchemaTable;
+    source?: DetailSource;
+    columns: TableColumn[];
+    columnsLoading: boolean;
+    columnsError: string | null;
+    activeTab: DetailTab;
+    onTabChange: (tab: DetailTab) => void;
+}
+
+const TAB_INDEX: DetailTab[] = ['data', 'columns', 'metadata', 'relationships'];
+
+export default function TableDetail({
+    table,
+    source,
+    columns,
+    columnsLoading,
+    columnsError,
+    activeTab,
+    onTabChange,
+}: TableDetailProps) {
+    const preview = useTablePreview(table.name);
+
+    const metaParts = [
+        `Source: ${source?.name ?? '—'}`,
+        `Schema: ${source?.schemaName ?? '—'}`,
+        `Type: ${table.tableType === 'VIEW' ? 'View' : 'Table'}`,
+        `Rows: ${typeof table.rows === 'number' ? table.rows.toLocaleString() : '—'}`,
+        `Last refreshed: ${table.updateTime ? formatRelativeTime(table.updateTime, { pastOnly: true }) : '—'}`,
+    ];
+
+    return (
+        <div className={`${styles.pane} ${styles.detailPane}`}>
+            <div className={styles.detailHeader}>
+                <span className={styles.detailIcon}>
+                    <TableBuilt size={22} />
+                </span>
+                <div className={styles.detailHeaderText}>
+                    <h4 className={styles.detailTitle} title={table.name}>
+                        Table: {table.name}
+                    </h4>
+                    <p className={styles.detailMeta}>{metaParts.join('     ')}</p>
+                </div>
+                <div className={styles.detailActions}>
+                    <Button kind="secondary" size="sm" renderIcon={Renew} onClick={preview.refresh}>
+                        Refresh
+                    </Button>
+                </div>
+            </div>
+
+            <div className={styles.detailBody}>
+                <Tabs
+                    selectedIndex={TAB_INDEX.indexOf(activeTab)}
+                    onChange={({ selectedIndex }) => onTabChange(TAB_INDEX[selectedIndex] ?? 'data')}>
+                    <TabList aria-label="Table detail tabs">
+                        <Tab>Data</Tab>
+                        <Tab>Columns</Tab>
+                        <Tab>Metadata</Tab>
+                        <Tab>Relationships</Tab>
+                    </TabList>
+                    <TabPanels>
+                        <TabPanel>
+                            <PreviewGrid
+                                table={table.name}
+                                data={preview.data}
+                                loading={preview.status === 'loading'}
+                                error={preview.error}
+                                onRefresh={preview.refresh}
+                            />
+                        </TabPanel>
+                        <TabPanel>
+                            <ColumnsTab columns={columns} loading={columnsLoading} error={columnsError} />
+                        </TabPanel>
+                        <TabPanel>
+                            <MetadataTab table={table} source={source} columns={columns} />
+                        </TabPanel>
+                        <TabPanel>
+                            <RelationshipsTab />
+                        </TabPanel>
+                    </TabPanels>
+                </Tabs>
+
+                <TableInfoStrip source={source} table={table} />
+            </div>
+        </div>
+    );
+}
+
+/** Empty detail pane shown when no table is selected */
+export function TableDetailEmpty() {
+    return (
+        <div className={`${styles.pane} ${styles.detailPane}`}>
+            <Tile className={styles.emptyState}>
+                <TableBuilt size={32} />
+                <h5>No table selected</h5>
+                <p>Select a table from the list to explore its columns and preview its data.</p>
+            </Tile>
+        </div>
+    );
+}

package/src/components/admin/etl-browser/table-info-strip.component.tsx

@@ -0,0 +1,51 @@
+/**
+ * Table information strip — one-line facts about the selected table.
+ */
+
+import React from 'react';
+import type { SchemaTable } from '../../../resources/theme/etl-schema.api';
+import { formatRelativeTime } from '../../../utils/etl-monitor/value-formatters.util';
+import type { DetailSource } from './table-detail.component';
+import styles from './etl-browser.component.scss';
+
+interface TableInfoStripProps {
+    source?: DetailSource;
+    table?: SchemaTable | null;
+}
+
+export default function TableInfoStrip({ source, table }: TableInfoStripProps) {
+    if (!table) {
+        return null;
+    }
+
+    const cells: Array<{ label: string; value: React.ReactNode }> = [
+        { label: 'Source', value: source?.name ?? '—' },
+        { label: 'Schema', value: source?.schemaName ?? '—' },
+        { label: 'Table', value: table.name },
+        { label: 'Type', value: table.tableType === 'VIEW' ? 'View' : 'Table' },
+        {
+            label: 'Rows',
+            value:
+                typeof table.rows === 'number' ? (
+                    <strong>{table.rows.toLocaleString()}</strong>
+                ) : (
+                    '—'
+                ),
+        },
+        {
+            label: 'Last refreshed',
+            value: table.updateTime ? formatRelativeTime(table.updateTime, { pastOnly: true }) : '—',
+        },
+    ];
+
+    return (
+        <div className={styles.infoStrip}>
+            {cells.map((cell) => (
+                <div key={cell.label} className={styles.infoCell}>
+                    <span className={styles.infoLabel}>{cell.label}</span>
+                    <span className={styles.infoValue}>{cell.value}</span>
+                </div>
+            ))}
+        </div>
+    );
+}

package/src/components/admin/etl-browser/table-list.component.tsx

@@ -0,0 +1,136 @@
+/**
+ * Middle pane — searchable list of the tables in the selected source
+ * (or all tables), with approximate row counts and freshness subtitles.
+ */
+
+import React from 'react';
+import { Button, InlineLoading, InlineNotification, Search, Tag } from '@carbon/react';
+import { CaretLeft, CaretRight, TableBuilt } from '@carbon/react/icons';
+import classNames from 'classnames';
+import type { SchemaTable } from '../../../resources/theme/etl-schema.api';
+import { formatRelativeTime } from '../../../utils/etl-monitor/value-formatters.util';
+import styles from './etl-browser.component.scss';
+
+interface TableListProps {
+    title: string;
+    tables: SchemaTable[];
+    selectedTable: string | null;
+    searchValue: string;
+    loading: boolean;
+    error: string | null;
+    /** Panel collapsed to a slim strip (linelist workspace pattern) */
+    collapsed?: boolean;
+    onToggleCollapsed?: () => void;
+    /** Shown as a reset control when a single source is in scope */
+    onResetFilter?: () => void;
+    onSearchChange: (value: string) => void;
+    onSelectTable: (tableName: string) => void;
+}
+
+function tableSubtitle(table: SchemaTable): string {
+    const rows = typeof table.rows === 'number' ? `${table.rows.toLocaleString()} rows` : 'rows unknown';
+    const freshness = table.updateTime ? formatRelativeTime(table.updateTime, { pastOnly: true }) : '—';
+    return `${rows} • ${freshness}`;
+}
+
+export default function TableList({
+    title,
+    tables,
+    selectedTable,
+    searchValue,
+    loading,
+    error,
+    collapsed = false,
+    onToggleCollapsed,
+    onResetFilter,
+    onSearchChange,
+    onSelectTable,
+}: TableListProps) {
+    const query = searchValue.trim().toLowerCase();
+    const visible = query ? tables.filter((t) => t.name.toLowerCase().includes(query)) : tables;
+
+    return (
+        <div className={styles.pane}>
+            <div className={styles.paneHeader}>
+                {!collapsed && (
+                    <>
+                        <span className={styles.paneTitle}>{title}</span>
+                        <span className={styles.paneActions}>
+                            {onResetFilter && (
+                                <button type="button" className={styles.iconAction} title="Show all sources" onClick={onResetFilter}>
+                                    All sources
+                                </button>
+                            )}
+                            <Tag size="sm" type="cool-gray">
+                                {tables.length}
+                            </Tag>
+                            {onToggleCollapsed && (
+                                <Button
+                                    kind="ghost"
+                                    size="sm"
+                                    hasIconOnly
+                                    renderIcon={CaretLeft}
+                                    iconDescription="Collapse panel"
+                                    onClick={onToggleCollapsed}
+                                />
+                            )}
+                        </span>
+                    </>
+                )}
+                {collapsed && onToggleCollapsed && (
+                    <Button
+                        kind="ghost"
+                        size="sm"
+                        hasIconOnly
+                        renderIcon={CaretRight}
+                        iconDescription="Expand panel"
+                        onClick={onToggleCollapsed}
+                    />
+                )}
+            </div>
+            {!collapsed && (
+                <>
+                    <div className={styles.paneSearch}>
+                        <Search
+                            size="sm"
+                            placeholder="Search tables..."
+                            labelText="Search tables"
+                            value={searchValue}
+                            onChange={(e) => onSearchChange((e as React.ChangeEvent<HTMLInputElement>).target.value)}
+                        />
+                    </div>
+                    <div className={styles.paneBody}>
+                        {loading && <InlineLoading description="Loading tables..." />}
+                        {error && <InlineNotification lowContrast kind="error" title="Error" subtitle={error} />}
+                        {!loading && !error && visible.length === 0 && (
+                            <p className={styles.treeEmpty}>No tables match</p>
+                        )}
+                        {visible.length > 0 && (
+                            <ul className={styles.tableList}>
+                                {visible.map((table) => (
+                                    <li key={table.name}>
+                                        <button
+                                            type="button"
+                                            className={classNames(
+                                                styles.tableRow,
+                                                selectedTable === table.name && styles.tableRowSelected,
+                                            )}
+                                            onClick={() => onSelectTable(table.name)}>
+                                            <span className={styles.tableRowIcon}>
+                                                <TableBuilt size={18} />
+                                            </span>
+                                            <span className={styles.tableRowText}>
+                                                <span className={styles.tableName}>{table.name}</span>
+                                                <span className={styles.tableMeta}>{tableSubtitle(table)}</span>
+                                            </span>
+                                        </button>
+                                    </li>
+                                ))}
+                            </ul>
+                        )}
+                    </div>
+                </>
+            )}
+        </div>
+    );
+}

package/src/components/admin/etl-browser/use-table-preview.ts

@@ -0,0 +1,47 @@
+/**
+ * useTablePreview — fetches a ≤1000-row preview of one ETL table via
+ * /reportbuilder/sqlpreview. State resets synchronously on table change so a
+ * slow previous fetch can never flash stale rows.
+ */
+
+import React from 'react';
+import { previewSql } from '../../../resources/preview/sql-preview.api';
+import type { SqlPreviewResponse } from '../../../resources/preview/sql-preview.api';
+import { buildTablePreviewSql } from '../../../utils/etl-browser';
+
+export type TablePreviewState = {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    data?: SqlPreviewResponse;
+    error?: string;
+};
+
+export function useTablePreview(table?: string | null): TablePreviewState & { refresh: () => void } {
+    const [state, setState] = React.useState<TablePreviewState>({ status: 'idle' });
+    const [refreshTick, setRefreshTick] = React.useState(0);
+
+    React.useEffect(() => {
+        if (!table) {
+            setState({ status: 'idle' });
+            return;
+        }
+
+        setState({ status: 'loading' });
+        const ac = new AbortController();
+
+        previewSql({ sql: buildTablePreviewSql(table), maxRows: 1000 }, ac.signal)
+            .then((data) => {
+                if (!ac.signal.aborted) {
+                    setState({ status: 'ready', data });
+                }
+            })
+            .catch((e) => {
+                if (e?.name !== 'AbortError') {
+                    setState({ status: 'error', error: e?.message ?? 'Failed to load preview' });
+                }
+            });
+
+        return () => ac.abort();
+    }, [table, refreshTick]);
+
+    return { ...state, refresh: () => setRefreshTick((tick) => tick + 1) };
+}