@visns-studio/visns-components 6.1.7 → 6.2.0

package/src/components/generic/reportSemanticSteps/SemanticParameterPrompt.jsx

@@ -0,0 +1,157 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import {
+    parameterFieldPath,
+    resolveFieldPath,
+    emptyParameterValue,
+} from '../reportSemantics';
+import SemanticValueInput, {
+    SemanticValueListInput,
+} from './SemanticValueInput';
+import styles from '../../styles/ReportSemantic.module.scss';
+
+const RANGE_TYPES = ['date_range', 'number_range', 'range'];
+const LIST_TYPES = ['enum_multi', 'list'];
+
+/** The value input type a range/list parameter uses for each of its slots. */
+const slotType = (parameterType) => {
+    switch (parameterType) {
+        case 'date_range':
+            return 'date';
+        case 'number_range':
+            return 'number';
+        case 'enum_multi':
+        case 'enum':
+            return 'enum';
+        case 'datetime':
+            return 'datetime';
+        case 'date':
+            return 'date';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        default:
+            return 'text';
+    }
+};
+
+/**
+ * Collects the runtime answers for a report's parameters.
+ *
+ * Values are POSTed as `parameters: {due_range: ['2026-01-01','2026-03-31']}`
+ * alongside the definition — ranges and lists as arrays, everything else as a
+ * scalar.
+ */
+const SemanticParameterPrompt = ({
+    model,
+    entityId,
+    filterTree,
+    parameters,
+    values,
+    onChange,
+}) => {
+    if (!parameters || parameters.length === 0) return null;
+
+    return (
+        <div className={styles.section}>
+            <div className={styles.sectionIntro}>
+                <h3>Before we run this report</h3>
+                <p>Answer these to decide which records are included.</p>
+            </div>
+
+            <div className={styles.parameterList}>
+                {parameters.map((parameter) => {
+                    const path = parameterFieldPath(filterTree, parameter.id);
+                    const resolved = resolveFieldPath(model, entityId, path);
+                    const type = slotType(parameter.type);
+                    const value =
+                        values?.[parameter.id] ??
+                        emptyParameterValue(parameter.type);
+
+                    return (
+                        <div
+                            key={parameter.id}
+                            className={styles.parameterRow}
+                        >
+                            <span className={styles.parameterLabel}>
+                                {parameter.label}
+                                {parameter.required !== false ? ' *' : ''}
+                            </span>
+
+                            {RANGE_TYPES.includes(parameter.type) ? (
+                                <span className={styles.conditionValues}>
+                                    <SemanticValueInput
+                                        type={type}
+                                        field={resolved?.field}
+                                        value={value?.[0] ?? ''}
+                                        ariaLabel={`${parameter.label} from`}
+                                        onChange={(next) =>
+                                            onChange(parameter.id, [
+                                                next,
+                                                value?.[1] ?? '',
+                                            ])
+                                        }
+                                    />
+                                    <span>and</span>
+                                    <SemanticValueInput
+                                        type={type}
+                                        field={resolved?.field}
+                                        value={value?.[1] ?? ''}
+                                        ariaLabel={`${parameter.label} to`}
+                                        onChange={(next) =>
+                                            onChange(parameter.id, [
+                                                value?.[0] ?? '',
+                                                next,
+                                            ])
+                                        }
+                                    />
+                                </span>
+                            ) : LIST_TYPES.includes(parameter.type) ? (
+                                <SemanticValueListInput
+                                    type={type}
+                                    field={resolved?.field}
+                                    values={
+                                        Array.isArray(value) ? value : []
+                                    }
+                                    onChange={(next) =>
+                                        onChange(parameter.id, next)
+                                    }
+                                />
+                            ) : (
+                                <SemanticValueInput
+                                    type={type}
+                                    field={resolved?.field}
+                                    value={value}
+                                    ariaLabel={parameter.label}
+                                    onChange={(next) =>
+                                        onChange(parameter.id, next)
+                                    }
+                                />
+                            )}
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+};
+
+SemanticParameterPrompt.propTypes = {
+    model: PropTypes.object,
+    entityId: PropTypes.string,
+    filterTree: PropTypes.object,
+    parameters: PropTypes.array,
+    values: PropTypes.object,
+    onChange: PropTypes.func.isRequired,
+};
+
+SemanticParameterPrompt.defaultProps = {
+    model: null,
+    entityId: '',
+    filterTree: null,
+    parameters: [],
+    values: {},
+};
+
+export default SemanticParameterPrompt;

package/src/components/generic/reportSemanticSteps/SemanticPreviewStep.jsx

@@ -0,0 +1,352 @@
+import React, { useMemo } from 'react';
+import PropTypes from 'prop-types';
+import { AlertTriangle } from 'lucide-react';
+import GroupedReportRenderer from '../GroupedReportRenderer';
+import {
+    formatSemanticValue,
+    parametersSatisfied,
+    resolveFieldPath,
+    selectionHeader,
+    selectionKey,
+} from '../reportSemantics';
+import SemanticParameterPrompt from './SemanticParameterPrompt';
+import styles from '../../styles/ReportSemantic.module.scss';
+
+const NUMERIC_TYPES = ['number', 'money', 'percent'];
+
+/**
+ * Column descriptors for the preview: `key` is the exact row key the server
+ * promised (field path, or the aggregate label), `header` is always the user's
+ * own wording. This is the fix for headers previously being raw server keys.
+ */
+export const buildPreviewColumns = (model, entityId, selections) =>
+    (selections || []).map((selection) => {
+        const resolved = resolveFieldPath(model, entityId, selection.path);
+        return {
+            key: selectionKey(selection),
+            header: selectionHeader(model, entityId, selection),
+            // A count is a plain number whatever the underlying field was.
+            type: selection.agg === 'count' ? 'number' : resolved?.type,
+            field: resolved?.field || null,
+        };
+    });
+
+/** Client-side sectioning for a report the user chose to group. */
+const buildGroups = (rows, columns, groupKey) => {
+    const buckets = new Map();
+    const groupColumn = columns.find((entry) => entry.key === groupKey);
+
+    rows.forEach((row) => {
+        const label =
+            formatSemanticValue(
+                row[groupKey],
+                groupColumn?.type,
+                groupColumn?.field
+            ) || 'Not set';
+        if (!buckets.has(label)) buckets.set(label, []);
+        buckets.get(label).push(row);
+    });
+
+    return Array.from(buckets.entries()).map(([label, groupRows]) => ({
+        groupName: label,
+        groupDisplayName: label,
+        totalRows: groupRows.length,
+        rows: groupRows.map((row) =>
+            columns.reduce((acc, column) => {
+                acc[column.key] = formatSemanticValue(
+                    row[column.key],
+                    column.type,
+                    column.field
+                );
+                return acc;
+            }, {})
+        ),
+    }));
+};
+
+/**
+ * Step 6 in semantic mode: answer any run-time questions, run the report, and
+ * review the results before saving or exporting.
+ */
+const SemanticPreviewStep = ({
+    model,
+    entityId,
+    selections,
+    filterTree,
+    parameters,
+    parameterValues,
+    groupBy,
+    rows,
+    total,
+    page,
+    pageSize,
+    isLoading,
+    error,
+    onChangeParameterValue,
+    onRun,
+    onChangePage,
+    onChangePageSize,
+    onExport,
+    onSave,
+    canSave,
+}) => {
+    const columns = useMemo(
+        () => buildPreviewColumns(model, entityId, selections),
+        [model, entityId, selections]
+    );
+
+    const ready = parametersSatisfied(parameters, parameterValues);
+    const groupKey = (groupBy || [])[0] || '';
+    const grouped = !!groupKey && rows.length > 0;
+    const totalPages = pageSize > 0 ? Math.ceil((total || 0) / pageSize) : 0;
+
+    const groups = useMemo(
+        () => (grouped ? buildGroups(rows, columns, groupKey) : []),
+        [grouped, rows, columns, groupKey]
+    );
+
+    return (
+        <div className={styles.section}>
+            <SemanticParameterPrompt
+                model={model}
+                entityId={entityId}
+                filterTree={filterTree}
+                parameters={parameters}
+                values={parameterValues}
+                onChange={onChangeParameterValue}
+            />
+
+            <div className={styles.previewActions}>
+                <button
+                    type="button"
+                    className={styles.toggleButton}
+                    disabled={isLoading || !ready || selections.length === 0}
+                    onClick={() => onRun({ page: 1 })}
+                >
+                    {isLoading ? 'Running…' : 'Run report'}
+                </button>
+
+                <button
+                    type="button"
+                    className={styles.toggleButton}
+                    disabled={!canSave}
+                    onClick={onSave}
+                >
+                    Save report
+                </button>
+
+                <span className={styles.aggPicker}>
+                    <span>Export as:</span>
+                    <select
+                        className={styles.select}
+                        aria-label="Export format"
+                        defaultValue=""
+                        onChange={(event) => {
+                            if (event.target.value) {
+                                onExport(event.target.value);
+                                event.target.value = '';
+                            }
+                        }}
+                        disabled={rows.length === 0 || isLoading}
+                    >
+                        <option value="">Choose…</option>
+                        <option value="xlsx">Excel</option>
+                        <option value="csv">CSV</option>
+                        <option value="pdf">PDF</option>
+                    </select>
+                </span>
+            </div>
+
+            {!ready && (parameters || []).length > 0 && (
+                <span className={styles.cardMeta}>
+                    Answer the questions above to run this report.
+                </span>
+            )}
+
+            {error && (
+                <div className={styles.errorPanel} role="alert">
+                    <AlertTriangle size={16} />
+                    <span>{error}</span>
+                </div>
+            )}
+
+            {isLoading && <div className={styles.loading}>Running your report…</div>}
+
+            {!isLoading && !error && rows.length === 0 && (
+                <div className={styles.empty}>
+                    No results yet. Run the report to see your data.
+                </div>
+            )}
+
+            {!isLoading && rows.length > 0 && grouped && (
+                <GroupedReportRenderer
+                    data={{
+                        grouped: true,
+                        groups,
+                        totalGroups: groups.length,
+                        totalRecords: total || rows.length,
+                    }}
+                    config={{
+                        type: 'sections',
+                        groupDisplayName:
+                            columns.find((column) => column.key === groupKey)
+                                ?.header || 'Group',
+                        showGroupTotals: true,
+                    }}
+                    columns={columns.map((column) => ({
+                        key: column.key,
+                        header: column.header,
+                    }))}
+                />
+            )}
+
+            {!isLoading && rows.length > 0 && !grouped && (
+                <>
+                    <div className={styles.summaryBar}>
+                        <span>
+                            Showing {rows.length} of {total || rows.length}{' '}
+                            records
+                        </span>
+                        <span className={styles.aggPicker}>
+                            <span>Rows per page:</span>
+                            <select
+                                className={styles.select}
+                                aria-label="Rows per page"
+                                value={pageSize}
+                                onChange={(event) =>
+                                    onChangePageSize(
+                                        Number(event.target.value)
+                                    )
+                                }
+                            >
+                                {[10, 25, 50, 100].map((size) => (
+                                    <option key={size} value={size}>
+                                        {size}
+                                    </option>
+                                ))}
+                            </select>
+                        </span>
+                    </div>
+
+                    <div className={styles.tableWrapper}>
+                        <table className={styles.previewTable}>
+                            <thead>
+                                <tr>
+                                    {columns.map((column) => (
+                                        <th key={column.key}>
+                                            {column.header}
+                                        </th>
+                                    ))}
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {rows.map((row, rowIndex) => (
+                                    <tr key={row.id || rowIndex}>
+                                        {columns.map((column) => {
+                                            const formatted =
+                                                formatSemanticValue(
+                                                    row[column.key],
+                                                    column.type,
+                                                    column.field
+                                                );
+                                            return (
+                                                <td
+                                                    key={column.key}
+                                                    className={
+                                                        NUMERIC_TYPES.includes(
+                                                            column.type
+                                                        )
+                                                            ? styles.numericCell
+                                                            : undefined
+                                                    }
+                                                >
+                                                    {formatted === '' ? (
+                                                        <span
+                                                            className={
+                                                                styles.emptyCell
+                                                            }
+                                                        >
+                                                            —
+                                                        </span>
+                                                    ) : (
+                                                        formatted
+                                                    )}
+                                                </td>
+                                            );
+                                        })}
+                                    </tr>
+                                ))}
+                            </tbody>
+                        </table>
+                    </div>
+
+                    {totalPages > 1 && (
+                        <div className={styles.previewActions}>
+                            <button
+                                type="button"
+                                className={styles.toggleButton}
+                                disabled={page <= 1 || isLoading}
+                                onClick={() => onChangePage(page - 1)}
+                            >
+                                Previous
+                            </button>
+                            <span className={styles.cardMeta}>
+                                Page {page} of {totalPages}
+                            </span>
+                            <button
+                                type="button"
+                                className={styles.toggleButton}
+                                disabled={page >= totalPages || isLoading}
+                                onClick={() => onChangePage(page + 1)}
+                            >
+                                Next
+                            </button>
+                        </div>
+                    )}
+                </>
+            )}
+        </div>
+    );
+};
+
+SemanticPreviewStep.propTypes = {
+    model: PropTypes.object,
+    entityId: PropTypes.string,
+    selections: PropTypes.array,
+    filterTree: PropTypes.object,
+    parameters: PropTypes.array,
+    parameterValues: PropTypes.object,
+    groupBy: PropTypes.arrayOf(PropTypes.string),
+    rows: PropTypes.array,
+    total: PropTypes.number,
+    page: PropTypes.number,
+    pageSize: PropTypes.number,
+    isLoading: PropTypes.bool,
+    error: PropTypes.string,
+    onChangeParameterValue: PropTypes.func.isRequired,
+    onRun: PropTypes.func.isRequired,
+    onChangePage: PropTypes.func.isRequired,
+    onChangePageSize: PropTypes.func.isRequired,
+    onExport: PropTypes.func.isRequired,
+    onSave: PropTypes.func.isRequired,
+    canSave: PropTypes.bool,
+};
+
+SemanticPreviewStep.defaultProps = {
+    model: null,
+    entityId: '',
+    selections: [],
+    filterTree: null,
+    parameters: [],
+    parameterValues: {},
+    groupBy: [],
+    rows: [],
+    total: 0,
+    page: 1,
+    pageSize: 25,
+    isLoading: false,
+    error: '',
+    canSave: false,
+};
+
+export default SemanticPreviewStep;

package/src/components/generic/reportSemanticSteps/SemanticRelationsStep.jsx

@@ -0,0 +1,154 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { CheckCircle, Info } from 'lucide-react';
+import {
+    cardinalityHint,
+    getEntityLabel,
+    listRelations,
+} from '../reportSemantics';
+import styles from '../../styles/ReportSemantic.module.scss';
+
+/** How many relation hops away from the root entity the picker will offer. */
+export const MAX_RELATION_DEPTH = 3;
+
+/**
+ * Every relation path reachable from `entityId`, given the ones already added.
+ * A relation is offered when its parent is the root entity or an added path,
+ * which lets the user chain (`adviser` then `adviser.team`) without ever
+ * facing the full transitive closure of the model.
+ */
+export const availableRelationPaths = (model, entityId, addedPaths) => {
+    if (!model || !entityId) return [];
+
+    const options = [];
+    const seen = new Set();
+
+    const expand = (fromEntity, prefix, depth) => {
+        if (depth > MAX_RELATION_DEPTH) return;
+        listRelations(model, fromEntity).forEach((relation) => {
+            const path = prefix ? `${prefix}.${relation.id}` : relation.id;
+            if (seen.has(path)) return;
+            seen.add(path);
+            options.push({ ...relation, path, depth, parentPath: prefix });
+            if ((addedPaths || []).includes(path)) {
+                expand(relation.entity, path, depth + 1);
+            }
+        });
+    };
+
+    expand(entityId, '', 1);
+    return options;
+};
+
+/**
+ * Step 2 in semantic mode: choose which related areas to pull in.
+ *
+ * There are no join columns here — joins do not exist in semantic mode. The
+ * server already declared how each relation connects; the user only decides
+ * whether they want it.
+ */
+const SemanticRelationsStep = ({
+    model,
+    entityId,
+    addedRelations,
+    onToggle,
+}) => {
+    const options = availableRelationPaths(model, entityId, addedRelations);
+    const entityLabel = getEntityLabel(model, entityId);
+
+    if (options.length === 0) {
+        return (
+            <div className={styles.section}>
+                <div className={styles.sectionIntro}>
+                    <h3>No related areas available</h3>
+                    <p>
+                        {entityLabel} has no connected information, so you can
+                        move straight on to choosing what to show.
+                    </p>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className={styles.section}>
+            <div className={styles.sectionIntro}>
+                <h3>Bring in related information</h3>
+                <p>
+                    Add anything connected to {entityLabel.toLowerCase()} that
+                    you want to show or filter on. This step is optional.
+                </p>
+            </div>
+
+            <div className={styles.cardGrid}>
+                {options.map((relation) => {
+                    const isAdded = (addedRelations || []).includes(
+                        relation.path
+                    );
+                    const parentLabel = relation.parentPath
+                        ? options.find(
+                              (candidate) =>
+                                  candidate.path === relation.parentPath
+                          )?.label
+                        : null;
+
+                    return (
+                        <button
+                            key={relation.path}
+                            type="button"
+                            className={`${styles.card} ${
+                                isAdded ? styles.selected : ''
+                            }`}
+                            aria-pressed={isAdded}
+                            onClick={() => onToggle(relation.path)}
+                        >
+                            <span className={styles.cardTitle}>
+                                <span>
+                                    {parentLabel
+                                        ? `${parentLabel} › ${relation.label}`
+                                        : relation.label}
+                                </span>
+                                {isAdded && <CheckCircle size={16} />}
+                            </span>
+                            {relation.description && (
+                                <span className={styles.cardDescription}>
+                                    {relation.description}
+                                </span>
+                            )}
+                            <span
+                                className={`${styles.badge} ${
+                                    relation.cardinality === 'many'
+                                        ? styles.badgeMany
+                                        : ''
+                                }`}
+                            >
+                                {cardinalityHint(relation)}
+                            </span>
+                        </button>
+                    );
+                })}
+            </div>
+
+            <div className={styles.cardMeta}>
+                <Info size={14} /> Adding an area that has many records per{' '}
+                {entityLabel.toLowerCase()} can repeat rows. Summarising those
+                fields (count, total) at the next step keeps one row per record.
+            </div>
+        </div>
+    );
+};
+
+SemanticRelationsStep.propTypes = {
+    model: PropTypes.object,
+    entityId: PropTypes.string,
+    addedRelations: PropTypes.arrayOf(PropTypes.string),
+    onToggle: PropTypes.func.isRequired,
+};
+
+SemanticRelationsStep.defaultProps = {
+    model: null,
+    entityId: '',
+    addedRelations: [],
+};
+
+export default SemanticRelationsStep;