@visns-studio/visns-components 6.1.7 → 6.2.0

package/src/components/generic/GenericReport.jsx

@@ -38,6 +38,31 @@ import debugLog from '../utils/debugLog';
 import { saveAs } from 'file-saver';
 import * as XLSX from 'xlsx';
 import Swal from 'sweetalert2';
+import useSemanticModel from './useSemanticModel';
+import {
+    DEFAULT_SEMANTIC_MODEL_URL,
+    appendToFilterGroup,
+    buildDefinition,
+    collectParameters,
+    createFilterCondition,
+    createFilterGroup,
+    createSelection,
+    defaultSelectionLabel,
+    emptyParameterValue,
+    getEntityLabel,
+    isSemanticDefinition,
+    parseDefinition,
+    parametersSatisfied,
+    relationPathsFromDefinition,
+    resolveFieldPath,
+    updateFilterNode,
+} from './reportSemantics';
+import SemanticEntityStep from './reportSemanticSteps/SemanticEntityStep';
+import SemanticRelationsStep from './reportSemanticSteps/SemanticRelationsStep';
+import SemanticFieldsStep from './reportSemanticSteps/SemanticFieldsStep';
+import SemanticFiltersStep from './reportSemanticSteps/SemanticFiltersStep';
+import SemanticGroupingStep from './reportSemanticSteps/SemanticGroupingStep';
+import SemanticPreviewStep from './reportSemanticSteps/SemanticPreviewStep';
 import styles from '../styles/GenericReport.module.scss';
 import '../styles/SweetAlert.module.css';
 import './groupedReport.css';
@@ -144,32 +169,6 @@ const getUniqueTableDisplayName = (tableName, allTables, definition) => {
     return `${baseDisplayName} (${tableName})`;
 };
 
-// Get structured table display name data for better styling
-const getStructuredTableDisplayName = (tableName, allTables, definition) => {
-    const baseDisplayName = getTableDisplayName(tableName, definition);
-
-    // Find all tables with the same display name
-    const conflictingTables = allTables.filter((table) => {
-        const otherTableName = typeof table === 'string' ? table : table.name;
-        const otherDisplayName = getTableDisplayName(
-            otherTableName,
-            definition
-        );
-        return (
-            otherDisplayName === baseDisplayName && otherTableName !== tableName
-        );
-    });
-
-    return {
-        main: baseDisplayName,
-        disambiguation: conflictingTables.length > 0 ? tableName : null,
-        full:
-            conflictingTables.length > 0
-                ? `${baseDisplayName} (${tableName})`
-                : baseDisplayName,
-    };
-};
-
 // Get table description from definition
 const getTableDescription = (tableName, definition) => {
     if (definition && definition.tables) {
@@ -1013,6 +1012,110 @@ const wizardSteps = [
     },
 ];
 
+/**
+ * Wizard steps used when the semantic model is available. Same six ids and the
+ * same order as `wizardSteps` — only the wording changes, because in this mode
+ * the user never sees a table, a column or a join.
+ */
+const semanticWizardSteps = [
+    {
+        id: 'table',
+        title: 'Choose Your Subject',
+        icon: Data,
+        description: 'What is this report about?',
+        guidance: {
+            summary: 'Pick the main thing you want to report on',
+            howTo: [
+                'Each card is a kind of record your system keeps',
+                'Read the description to check it is the one you mean',
+                'Click it to make it the subject of your report',
+                'You can bring in connected information at the next step',
+            ],
+            tip: 'Pick the thing you want one row per — for example one row per client.',
+        },
+    },
+    {
+        id: 'relationships',
+        title: 'Add Related Data',
+        icon: LinkChain,
+        description: 'Bring in connected information (optional)',
+        guidance: {
+            summary: 'Add areas connected to your subject',
+            howTo: [
+                'Each card is an area of information already connected for you',
+                'Click one to make its details available in the next step',
+                'Areas marked "many per record" can repeat rows',
+                'Skip this step if the main subject has everything you need',
+            ],
+            tip: 'Summarising a "many per record" area (count, total) keeps one row per record.',
+        },
+    },
+    {
+        id: 'columns',
+        title: 'Choose Information',
+        icon: File,
+        description: 'Pick the details you want to see',
+        guidance: {
+            summary: 'Tick the details to include as columns',
+            howTo: [
+                'Details are grouped by the area they come from',
+                'Within each area they are sorted into kinds of information',
+                'Tick anything you want to see in the report',
+                'Use "Show as" to total, count or average a detail instead',
+            ],
+            tip: 'Start with how you identify a record, then add the numbers you care about.',
+        },
+    },
+    {
+        id: 'filters',
+        title: 'Filter Results',
+        icon: Filter,
+        description: 'Narrow down to specific records (optional)',
+        guidance: {
+            summary: 'Keep only the records you care about',
+            howTo: [
+                'Add a condition, then choose a detail and how to compare it',
+                'Switch a group between "all of these" and "any of these"',
+                'Nest a group to mix the two, e.g. active AND (email OR phone)',
+                'Tick "ask me each time" to be prompted for the value at run time',
+            ],
+            tip: 'Anything you might change week to week is better asked at run time than fixed here.',
+        },
+    },
+    {
+        id: 'grouping',
+        title: 'Group & Order',
+        icon: Data,
+        description: 'Organise the results (optional)',
+        guidance: {
+            summary: 'Split the report into sections and set the row order',
+            howTo: [
+                'Tick a column to break the report into sections by its value',
+                'Add a sort to control the order rows appear in',
+                'Only columns you chose to show can be used here',
+                'Skip this step for a plain list',
+            ],
+            tip: 'Grouping suits reports like "clients by adviser".',
+        },
+    },
+    {
+        id: 'preview',
+        title: 'Preview & Save',
+        icon: EyeOpen,
+        description: 'Review your report and save it for reuse',
+        guidance: {
+            summary: 'Run, review, save and export',
+            howTo: [
+                'Answer any run-time questions you set up',
+                'Click "Run report" to see your data',
+                'Save the report so you or your team can run it again',
+                'Export the results as Excel, CSV or PDF',
+            ],
+            tip: 'A saved report always runs against live data — save it once, run it whenever.',
+        },
+    },
+];
+
 // Icon mapping for business templates (moved from hardcoded templates)
 const getTemplateIcon = (iconName) => {
     const iconMap = {
@@ -1175,6 +1278,451 @@ const GenericReportImproved = ({
         exportUrl = '/ajax/reportBuilder/export',
     } = setting;
 
+    // `semanticModelUrl: null` (or false) opts a host app out of the probe
+    // entirely; omitting the key uses the contract default.
+    const semanticModelUrl =
+        'semanticModelUrl' in setting
+            ? setting.semanticModelUrl
+            : DEFAULT_SEMANTIC_MODEL_URL;
+
+    const {
+        model: semanticModel,
+        status: semanticStatus,
+        isSemantic,
+    } = useSemanticModel(
+        semanticModelUrl || DEFAULT_SEMANTIC_MODEL_URL,
+        !!semanticModelUrl
+    );
+
+    // ---- Semantic mode state -------------------------------------------
+    // All of it is inert while `isSemantic` is false, which is what keeps
+    // legacy mode byte-for-byte unchanged.
+    const [semanticEntity, setSemanticEntity] = useState('');
+    const [semanticRelations, setSemanticRelations] = useState([]);
+    const [semanticSelections, setSemanticSelections] = useState([]);
+    const [semanticFilterTree, setSemanticFilterTree] = useState(() =>
+        createFilterGroup('and', [])
+    );
+    const [semanticParameters, setSemanticParameters] = useState([]);
+    const [semanticParameterValues, setSemanticParameterValues] = useState({});
+    const [semanticGroupBy, setSemanticGroupBy] = useState([]);
+    const [semanticSort, setSemanticSort] = useState([]);
+    const [semanticRows, setSemanticRows] = useState([]);
+    const [semanticTotal, setSemanticTotal] = useState(0);
+    const [semanticPage, setSemanticPage] = useState(1);
+    const [semanticPageSize, setSemanticPageSize] = useState(25);
+    const [semanticError, setSemanticError] = useState('');
+    const [semanticHasRun, setSemanticHasRun] = useState(false);
+
+    const activeWizardSteps = isSemantic ? semanticWizardSteps : wizardSteps;
+
+    /* ---- Semantic mode handlers ---------------------------------------- */
+
+    const resetSemanticState = useCallback(() => {
+        setSemanticEntity('');
+        setSemanticRelations([]);
+        setSemanticSelections([]);
+        setSemanticFilterTree(createFilterGroup('and', []));
+        setSemanticParameters([]);
+        setSemanticParameterValues({});
+        setSemanticGroupBy([]);
+        setSemanticSort([]);
+        setSemanticRows([]);
+        setSemanticTotal(0);
+        setSemanticPage(1);
+        setSemanticError('');
+        setSemanticHasRun(false);
+    }, []);
+
+    const handleSemanticSelectEntity = (entityId) => {
+        if (entityId === semanticEntity) return;
+        // A different subject invalidates every path that was built on the
+        // previous one, so start the semantic side of the wizard over.
+        resetSemanticState();
+        setSemanticEntity(entityId);
+    };
+
+    const handleSemanticToggleRelation = (relationPath) => {
+        const isRemoving = semanticRelations.includes(relationPath);
+
+        if (!isRemoving) {
+            setSemanticRelations((previous) => [...previous, relationPath]);
+            return;
+        }
+
+        // Removing a relation also removes anything nested under it and every
+        // selection, filter, grouping and sort that reached through it.
+        const prefix = `${relationPath}.`;
+        const isOrphaned = (path) =>
+            path === relationPath || String(path).startsWith(prefix);
+
+        setSemanticRelations((previous) =>
+            previous.filter((path) => !isOrphaned(path))
+        );
+        setSemanticSelections((previous) =>
+            previous.filter((selection) => !isOrphaned(selection.path))
+        );
+        setSemanticGroupBy((previous) =>
+            previous.filter((path) => !isOrphaned(path))
+        );
+        setSemanticSort((previous) =>
+            previous.filter((entry) => !isOrphaned(entry.field))
+        );
+        setSemanticFilterTree((previous) => {
+            const prune = (node) => {
+                if (node.kind === 'group') {
+                    return {
+                        ...node,
+                        items: (node.items || [])
+                            .map(prune)
+                            .filter((child) => child !== null),
+                    };
+                }
+                return isOrphaned(node.field) ? null : node;
+            };
+            return prune(previous);
+        });
+    };
+
+    const handleSemanticToggleField = (path) => {
+        setSemanticSelections((previous) => {
+            const exists = previous.some(
+                (selection) => selection.path === path
+            );
+            if (exists) {
+                return previous.filter(
+                    (selection) => selection.path !== path
+                );
+            }
+            const selection = createSelection(
+                semanticModel,
+                semanticEntity,
+                path
+            );
+            return selection ? [...previous, selection] : previous;
+        });
+    };
+
+    const handleSemanticChangeAggregate = (path, agg) => {
+        setSemanticSelections((previous) =>
+            previous.map((selection) => {
+                if (selection.path !== path) return selection;
+                const resolved = resolveFieldPath(
+                    semanticModel,
+                    semanticEntity,
+                    path
+                );
+                if (!resolved) return selection;
+                return {
+                    ...selection,
+                    agg: agg || '',
+                    label: defaultSelectionLabel(resolved, agg),
+                };
+            })
+        );
+
+        // An aggregate cannot also be the grouping key.
+        if (agg) {
+            setSemanticGroupBy((previous) =>
+                previous.filter((entry) => entry !== path)
+            );
+        }
+    };
+
+    const handleSemanticRemoveSelection = (path, agg) => {
+        setSemanticSelections((previous) =>
+            previous.filter(
+                (selection) =>
+                    !(
+                        selection.path === path &&
+                        (selection.agg || '') === (agg || '')
+                    )
+            )
+        );
+        setSemanticGroupBy((previous) =>
+            previous.filter((entry) => entry !== path)
+        );
+        setSemanticSort((previous) =>
+            previous.filter((entry) => entry.field !== path)
+        );
+    };
+
+    const handleSemanticMoveSelection = (from, to) => {
+        setSemanticSelections((previous) => {
+            if (to < 0 || to >= previous.length) return previous;
+            const next = [...previous];
+            const [moved] = next.splice(from, 1);
+            next.splice(to, 0, moved);
+            return next;
+        });
+    };
+
+    const handleSemanticChangeFilterNode = (nodeId, patch) => {
+        setSemanticFilterTree((previous) =>
+            updateFilterNode(previous, nodeId, (node) => ({
+                ...node,
+                ...patch,
+            }))
+        );
+    };
+
+    const handleSemanticRemoveFilterNode = (nodeId) => {
+        setSemanticFilterTree((previous) =>
+            updateFilterNode(previous, nodeId, () => null)
+        );
+    };
+
+    const handleSemanticAddFilterCondition = (groupId) => {
+        setSemanticFilterTree((previous) =>
+            appendToFilterGroup(previous, groupId, createFilterCondition())
+        );
+    };
+
+    const handleSemanticAddFilterGroup = (groupId) => {
+        setSemanticFilterTree((previous) =>
+            appendToFilterGroup(
+                previous,
+                groupId,
+                createFilterGroup('or', [createFilterCondition()])
+            )
+        );
+    };
+
+    const handleSemanticChangeParameter = (parameterId, patch) => {
+        setSemanticParameters((previous) =>
+            previous.map((parameter) =>
+                parameter.id === parameterId
+                    ? { ...parameter, ...patch }
+                    : parameter
+            )
+        );
+    };
+
+    const handleSemanticChangeParameterValue = (parameterId, value) => {
+        setSemanticParameterValues((previous) => ({
+            ...previous,
+            [parameterId]: value,
+        }));
+    };
+
+    const handleSemanticToggleGroupBy = (path) => {
+        setSemanticGroupBy((previous) =>
+            previous.includes(path)
+                ? previous.filter((entry) => entry !== path)
+                : [...previous, path]
+        );
+    };
+
+    const handleSemanticAddSort = (field, dir) => {
+        setSemanticSort((previous) => [...previous, { field, dir }]);
+    };
+
+    const handleSemanticChangeSort = (index, patch) => {
+        setSemanticSort((previous) =>
+            previous.map((entry, entryIndex) =>
+                entryIndex === index ? { ...entry, ...patch } : entry
+            )
+        );
+    };
+
+    const handleSemanticRemoveSort = (index) => {
+        setSemanticSort((previous) =>
+            previous.filter((entry, entryIndex) => entryIndex !== index)
+        );
+    };
+
+    // Parameter definitions are derived from the filter tree: ticking "ask me
+    // each time" creates one, unticking removes it. Edited labels survive.
+    useEffect(() => {
+        if (!isSemantic || !semanticEntity) return;
+        setSemanticParameters((previous) => {
+            const next = collectParameters(
+                semanticModel,
+                semanticEntity,
+                semanticFilterTree,
+                previous
+            );
+            const unchanged =
+                next.length === previous.length &&
+                next.every(
+                    (parameter, index) =>
+                        parameter.id === previous[index].id &&
+                        parameter.label === previous[index].label &&
+                        parameter.type === previous[index].type &&
+                        parameter.required === previous[index].required
+                );
+            return unchanged ? previous : next;
+        });
+    }, [isSemantic, semanticModel, semanticEntity, semanticFilterTree]);
+
+    // Seed a blank answer for each parameter so the inputs stay controlled.
+    useEffect(() => {
+        if (!isSemantic) return;
+        setSemanticParameterValues((previous) => {
+            const next = {};
+            semanticParameters.forEach((parameter) => {
+                next[parameter.id] =
+                    previous[parameter.id] ??
+                    emptyParameterValue(parameter.type);
+            });
+            return next;
+        });
+    }, [isSemantic, semanticParameters]);
+
+    /** The v2 document this wizard currently describes. */
+    const semanticDefinition = useMemo(() => {
+        if (!isSemantic || !semanticEntity) return null;
+        return buildDefinition({
+            model: semanticModel,
+            entity: semanticEntity,
+            selections: semanticSelections,
+            filterTree: semanticFilterTree,
+            parameters: semanticParameters,
+            groupBy: semanticGroupBy,
+            sort: semanticSort,
+        });
+    }, [
+        isSemantic,
+        semanticModel,
+        semanticEntity,
+        semanticSelections,
+        semanticFilterTree,
+        semanticParameters,
+        semanticGroupBy,
+        semanticSort,
+    ]);
+
+    /**
+     * The server's own words for a rejected definition.
+     *
+     * A bad definition comes back as HTTP 422 with
+     * `{success:false, message, errors:[{path, message}]}` — but a non-2xx
+     * response makes CustomFetch reject rather than resolve, so the body never
+     * reaches the `success === false` branch below. "Unknown field [x] on
+     * [clients]" is exactly what the user needs to fix the report, so dig it
+     * off the error before falling back to a generic line.
+     */
+    const semanticErrorMessage = (error, fallback) => {
+        const data = error?.response?.data;
+        if (typeof data?.message === 'string' && data.message) {
+            return data.message;
+        }
+        const first = Array.isArray(data?.errors) ? data.errors[0] : null;
+        if (typeof first?.message === 'string' && first.message) {
+            return first.message;
+        }
+        return fallback;
+    };
+
+    /**
+     * POST executeUrl {definition, parameters, limit, offset}
+     * -> {success, data: [rows], total}
+     */
+    const runSemanticReport = async ({ page, size } = {}) => {
+        if (!semanticDefinition || semanticSelections.length === 0) return;
+
+        const pageToLoad = page || semanticPage;
+        const sizeToLoad = size || semanticPageSize;
+
+        if (!parametersSatisfied(semanticParameters, semanticParameterValues)) {
+            setSemanticError(
+                'Answer every required question before running this report.'
+            );
+            return;
+        }
+
+        setIsLoading(true);
+        setSemanticError('');
+
+        try {
+            const result = await CustomFetch(
+                customUrls.executeUrl || executeUrl,
+                'POST',
+                {
+                    definition: semanticDefinition,
+                    parameters: semanticParameterValues,
+                    limit: sizeToLoad,
+                    offset: (pageToLoad - 1) * sizeToLoad,
+                },
+                null,
+                () => {},
+                { cache: false }
+            );
+
+            const body = result?.data;
+
+            if (body?.success === false) {
+                setSemanticRows([]);
+                setSemanticTotal(0);
+                setSemanticError(
+                    body.message || 'The report could not be run.'
+                );
+                return;
+            }
+
+            const rows = Array.isArray(body?.data) ? body.data : [];
+            setSemanticRows(rows);
+            setSemanticTotal(
+                typeof body?.total === 'number' ? body.total : rows.length
+            );
+            setSemanticPage(pageToLoad);
+            setSemanticPageSize(sizeToLoad);
+            setSemanticHasRun(true);
+        } catch (error) {
+            debugLog('Semantic report execution failed:', error);
+            setSemanticRows([]);
+            setSemanticTotal(0);
+            setSemanticError(
+                semanticErrorMessage(
+                    error,
+                    'We could not run this report. Please try again.'
+                )
+            );
+        } finally {
+            setIsLoading(false);
+        }
+    };
+
+    /** POST exportUrl {definition, parameters, format} -> blob */
+    const exportSemanticReport = async (format) => {
+        if (!semanticDefinition) return;
+
+        try {
+            const result = await Download(
+                customUrls.exportUrl || exportUrl,
+                'POST',
+                {
+                    definition: semanticDefinition,
+                    parameters: semanticParameterValues,
+                    format,
+                }
+            );
+
+            if (result?.data) {
+                const timestamp = moment().format('YYYY-MM-DD_HH-mm-ss');
+                const baseName = (
+                    reportName ||
+                    getEntityLabel(semanticModel, semanticEntity) ||
+                    'report'
+                ).replace(/[^a-zA-Z0-9]/g, '_');
+                saveAs(result.data, `${baseName}_${timestamp}.${format}`);
+                toast.success(`Report exported as ${format.toUpperCase()}`);
+            } else {
+                toast.error(
+                    `Failed to export report as ${format.toUpperCase()}`
+                );
+            }
+        } catch (error) {
+            debugLog('Semantic export failed:', error);
+            toast.error(
+                semanticErrorMessage(
+                    error,
+                    `Failed to export report as ${format.toUpperCase()}`
+                )
+            );
+        }
+    };
+
     // Simple icon helper for SweetAlert2 - returns HTML strings with SVG icons
     const getIcon = (iconName, color = '#6b7280', size = 16) => {
         const icons = {
@@ -1436,7 +1984,14 @@ const GenericReportImproved = ({
 
     // Initialize component
     useEffect(() => {
-        fetchDatabaseTables();
+        // Wait for the semantic probe to settle before hitting the legacy
+        // table endpoint: a semantic-only backend has no /getTables to call,
+        // and asking anyway would surface an error the user cannot act on.
+        if (semanticStatus === 'loading') return;
+        if (semanticStatus !== 'ready') {
+            fetchDatabaseTables();
+        }
+
         fetchSavedReports();
 
         // Show help on first load
@@ -1447,7 +2002,7 @@ const GenericReportImproved = ({
                 localStorage.setItem('reportBuilder_hasSeenHelp', 'true');
             }, 500);
         }
-    }, [tableUrl, reportsUrl]); // Add dependencies to ensure re-fetch when URLs change
+    }, [tableUrl, reportsUrl, semanticStatus]); // Re-fetch when URLs change
 
     // Fetch columns when table is selected (like advanced mode)
     useEffect(() => {
@@ -1522,6 +2077,7 @@ const GenericReportImproved = ({
     // Auto-execute report when user reaches step 5 (preview step)
     useEffect(() => {
         if (
+            !isSemantic && // Semantic mode has its own run trigger below
             currentWizardStep === 5 && // Step 6 is index 5 (preview step)
             selectedTable &&
             selectedColumns.length > 0 &&
@@ -1532,6 +2088,7 @@ const GenericReportImproved = ({
             executeReport();
         }
     }, [
+        isSemantic,
         currentWizardStep,
         selectedTable,
         selectedColumns.length,
@@ -1539,6 +2096,40 @@ const GenericReportImproved = ({
         hasAutoExecuted,
     ]);
 
+    // Semantic mode: run once on arriving at the preview step, but only when
+    // there is nothing to ask the user first — otherwise wait for their answers.
+    useEffect(() => {
+        if (!isSemantic) return;
+        if (currentWizardStep !== 5) return;
+        if (isLoading || semanticHasRun) return;
+        if (semanticSelections.length === 0) return;
+        if (!parametersSatisfied(semanticParameters, semanticParameterValues)) {
+            return;
+        }
+        runSemanticReport({ page: 1 });
+    }, [
+        isSemantic,
+        currentWizardStep,
+        isLoading,
+        semanticHasRun,
+        semanticSelections.length,
+        semanticParameters,
+        semanticParameterValues,
+    ]);
+
+    // Any change to the report design invalidates the results already on screen.
+    useEffect(() => {
+        if (!isSemantic) return;
+        setSemanticHasRun(false);
+    }, [
+        isSemantic,
+        semanticEntity,
+        semanticSelections,
+        semanticFilterTree,
+        semanticGroupBy,
+        semanticSort,
+    ]);
+
     // Escape closes whichever modal is open
     useEffect(() => {
         if (!showCalculatedFieldModal && !showRowExclusionModal) return undefined;
@@ -1724,6 +2315,9 @@ const GenericReportImproved = ({
         // Reset UI state
         setShowHiddenFields(false);
 
+        // Reset semantic mode state (inert in legacy mode)
+        resetSemanticState();
+
         toast.info(
             'Report builder reset. You can start creating a new report.'
         );
@@ -1731,7 +2325,7 @@ const GenericReportImproved = ({
 
     // Wizard navigation
     const goToNextStep = () => {
-        if (currentWizardStep < wizardSteps.length - 1) {
+        if (currentWizardStep < activeWizardSteps.length - 1) {
             setCurrentWizardStep(currentWizardStep + 1);
         }
     };
@@ -1744,6 +2338,25 @@ const GenericReportImproved = ({
 
     // Check if current step is complete
     const isStepComplete = (stepId) => {
+        if (isSemantic) {
+            switch (stepId) {
+                case 'table':
+                    return !!semanticEntity;
+                case 'relationships':
+                    return true; // Optional step
+                case 'columns':
+                    return semanticSelections.length > 0;
+                case 'filters':
+                    return true; // Optional step
+                case 'grouping':
+                    return true; // Optional step
+                case 'preview':
+                    return semanticHasRun;
+                default:
+                    return false;
+            }
+        }
+
         switch (stepId) {
             case 'table':
                 return !!selectedTable;
@@ -1813,15 +2426,15 @@ const GenericReportImproved = ({
                     return;
                 }
 
-                // Filter out hidden tables and tables with underscores (like advanced mode)
+                // Filter out hidden tables only. Snake_case names are ordinary
+                // table names — dropping them silently hid most of the schema.
                 let filteredTables = tableData
                     .filter((table) => {
                         const tableName =
                             typeof table === 'string' ? table : table?.name;
                         return (
                             typeof tableName === 'string' &&
-                            !hiddenTables.includes(tableName) &&
-                            !tableName.includes('_')
+                            !hiddenTables.includes(tableName)
                         );
                     })
                     .map((table) => {
@@ -2988,8 +3601,8 @@ const GenericReportImproved = ({
                 }
             }
 
-            if (currentWizardStep < wizardSteps.length - 1) {
-                setCurrentWizardStep(wizardSteps.length - 1);
+            if (currentWizardStep < activeWizardSteps.length - 1) {
+                setCurrentWizardStep(activeWizardSteps.length - 1);
             }
 
             // Report executed successfully
@@ -3033,6 +3646,40 @@ const GenericReportImproved = ({
                 return;
             }
 
+            // A v2 document restores the semantic wizard. A v1 document (it has
+            // `mainTable`) always falls through to the legacy path below, even
+            // when the semantic model happens to be available.
+            if (isSemanticDefinition(config)) {
+                if (!isSemantic) {
+                    toast.error(
+                        'This report needs the newer report engine, which is not available here.'
+                    );
+                    return;
+                }
+
+                const parsed = parseDefinition(config);
+                resetSemanticState();
+                setSemanticEntity(parsed.entity);
+                setSemanticSelections(parsed.selections);
+                setSemanticFilterTree(parsed.filterTree);
+                setSemanticParameters(parsed.parameters);
+                setSemanticGroupBy(parsed.groupBy);
+                setSemanticSort(parsed.sort);
+                // Re-derive which related areas the saved paths reach through,
+                // so the relations step shows them as already added.
+                setSemanticRelations(
+                    relationPathsFromDefinition(parsed, semanticModel)
+                );
+
+                setReportName(report.label || '');
+                setIsPublic(!!report.is_public);
+                setLoadedReportId(report.id);
+                setShowTemplates(false);
+                setCurrentWizardStep(0);
+                toast.success(`Loaded report: ${report.label}`);
+                return;
+            }
+
             if (config.mainTable) {
                 setSelectedTable(config.mainTable);
                 setAvailableTables([config.mainTable]);
@@ -3440,9 +4087,21 @@ const GenericReportImproved = ({
                             <h3>Your Saved Reports ({savedReports.length})</h3>
                             <div className={styles.reportsGrid}>
                                 {savedReports.map((report) => {
-                                    const reportMainTable =
-                                        parseReportDetail(report.detail)
-                                            ?.mainTable || '';
+                                    const reportDetail = parseReportDetail(
+                                        report.detail
+                                    );
+                                    // v1 reports show the table name; v2 ones
+                                    // show the entity's business label.
+                                    const reportSubject = isSemanticDefinition(
+                                        reportDetail
+                                    )
+                                        ? getEntityLabel(
+                                              semanticModel,
+                                              reportDetail.entity
+                                          )
+                                        : formatName(
+                                              reportDetail?.mainTable || ''
+                                          );
                                     return (
                                     <div
                                         key={report.id}
@@ -3497,7 +4156,7 @@ const GenericReportImproved = ({
                                                     </span>
                                                 </div>
                                             </div>
-                                            {reportMainTable && (
+                                            {reportSubject && (
                                                 <div
                                                     className={
                                                         styles.reportTableInfo
@@ -3517,9 +4176,7 @@ const GenericReportImproved = ({
                                                                     'middle',
                                                             }}
                                                         />
-                                                        {formatName(
-                                                            reportMainTable
-                                                        )}
+                                                        {reportSubject}
                                                     </span>
                                                 </div>
                                             )}
@@ -3571,14 +4228,14 @@ const GenericReportImproved = ({
 
     // Render wizard mode
     const renderWizardMode = () => {
-        const currentStep = wizardSteps[currentWizardStep];
+        const currentStep = activeWizardSteps[currentWizardStep];
         const StepIcon = currentStep.icon;
 
         return (
             <div className={styles.wizardMode}>
                 {/* Progress bar */}
                 <div className={styles.wizardProgress}>
-                    {wizardSteps.map((step, index) => {
+                    {activeWizardSteps.map((step, index) => {
                         const StepIcon = step.icon;
                         const isActive = index === currentWizardStep;
                         const isComplete =
@@ -3696,7 +4353,7 @@ const GenericReportImproved = ({
                             </button>
                         )}
 
-                        {currentWizardStep === wizardSteps.length - 1 ? (
+                        {currentWizardStep === activeWizardSteps.length - 1 ? (
                             <button
                                 type="button"
                                 className={`${styles.btn} ${styles.btnStartAgain}`}
@@ -3720,8 +4377,107 @@ const GenericReportImproved = ({
         );
     };
 
+    // Render the semantic-mode body for a step. Returns null in legacy mode so
+    // the caller falls through to the original renderers untouched.
+    const renderSemanticStepContent = (stepId) => {
+        switch (stepId) {
+            case 'table':
+                return (
+                    <SemanticEntityStep
+                        model={semanticModel}
+                        selectedEntity={semanticEntity}
+                        onSelect={handleSemanticSelectEntity}
+                    />
+                );
+            case 'relationships':
+                return (
+                    <SemanticRelationsStep
+                        model={semanticModel}
+                        entityId={semanticEntity}
+                        addedRelations={semanticRelations}
+                        onToggle={handleSemanticToggleRelation}
+                    />
+                );
+            case 'columns':
+                return (
+                    <SemanticFieldsStep
+                        model={semanticModel}
+                        entityId={semanticEntity}
+                        addedRelations={semanticRelations}
+                        selections={semanticSelections}
+                        onToggleField={handleSemanticToggleField}
+                        onChangeAggregate={handleSemanticChangeAggregate}
+                        onRemoveSelection={handleSemanticRemoveSelection}
+                        onMoveSelection={handleSemanticMoveSelection}
+                    />
+                );
+            case 'filters':
+                return (
+                    <SemanticFiltersStep
+                        model={semanticModel}
+                        entityId={semanticEntity}
+                        addedRelations={semanticRelations}
+                        filterTree={semanticFilterTree}
+                        parameters={semanticParameters}
+                        onChangeNode={handleSemanticChangeFilterNode}
+                        onRemoveNode={handleSemanticRemoveFilterNode}
+                        onAddCondition={handleSemanticAddFilterCondition}
+                        onAddGroup={handleSemanticAddFilterGroup}
+                        onChangeParameter={handleSemanticChangeParameter}
+                    />
+                );
+            case 'grouping':
+                return (
+                    <SemanticGroupingStep
+                        model={semanticModel}
+                        entityId={semanticEntity}
+                        selections={semanticSelections}
+                        groupBy={semanticGroupBy}
+                        sort={semanticSort}
+                        onToggleGroupBy={handleSemanticToggleGroupBy}
+                        onAddSort={handleSemanticAddSort}
+                        onChangeSort={handleSemanticChangeSort}
+                        onRemoveSort={handleSemanticRemoveSort}
+                    />
+                );
+            case 'preview':
+                return (
+                    <SemanticPreviewStep
+                        model={semanticModel}
+                        entityId={semanticEntity}
+                        selections={semanticSelections}
+                        filterTree={semanticFilterTree}
+                        parameters={semanticParameters}
+                        parameterValues={semanticParameterValues}
+                        groupBy={semanticGroupBy}
+                        rows={semanticRows}
+                        total={semanticTotal}
+                        page={semanticPage}
+                        pageSize={semanticPageSize}
+                        isLoading={isLoading}
+                        error={semanticError}
+                        onChangeParameterValue={handleSemanticChangeParameterValue}
+                        onRun={runSemanticReport}
+                        onChangePage={(page) => runSemanticReport({ page })}
+                        onChangePageSize={(size) =>
+                            runSemanticReport({ page: 1, size })
+                        }
+                        onExport={exportSemanticReport}
+                        onSave={() => saveReport(false)}
+                        canSave={semanticSelections.length > 0}
+                    />
+                );
+            default:
+                return null;
+        }
+    };
+
     // Render wizard step content
     const renderWizardStepContent = (stepId) => {
+        if (isSemantic) {
+            return renderSemanticStepContent(stepId);
+        }
+
         switch (stepId) {
             case 'table':
                 return renderTableSelection();
@@ -7341,10 +8097,15 @@ const GenericReportImproved = ({
 
     // Save report configuration (with save/save-as functionality)
     const saveReport = async (saveAs = false) => {
+        // In semantic mode the subject is an entity label, not a table name.
+        const subjectName = isSemantic
+            ? getEntityLabel(semanticModel, semanticEntity)
+            : formatName(selectedTable);
+
         if (!reportName.trim()) {
-            const defaultName = `${formatName(
-                selectedTable
-            )} Report - ${moment().format('YYYY-MM-DD')}`;
+            const defaultName = `${subjectName} Report - ${moment().format(
+                'YYYY-MM-DD'
+            )}`;
             setReportName(defaultName);
         }
 
@@ -7377,9 +8138,7 @@ const GenericReportImproved = ({
                             saveAs
                                 ? `${reportName} (Copy)`
                                 : reportName ||
-                                      `${formatName(
-                                          selectedTable
-                                      )} Report - ${moment().format(
+                                      `${subjectName} Report - ${moment().format(
                                           'YYYY-MM-DD'
                                       )}`
                         )}"
@@ -7416,24 +8175,32 @@ const GenericReportImproved = ({
 
         if (result.isConfirmed) {
             try {
-                const reportConfig = {
-                    label: result.value.name,
-                    is_public: result.value.isPublic,
-                    detail: {
-                        mainTable: selectedTable,
-                        columns: selectedColumns,
-                        joins: joins,
-                        filters: filterCriteria,
-                        sorting: sortCriteria,
-                        grouping: groupingConfig.enabled
-                            ? groupingConfig
-                            : null,
-                        isGrouped: groupingConfig.enabled,
-                        customCalculatedFields: customCalculatedFields,
-                        customUrls: customUrls,
-                        unique: uniqueFieldConfig,
-                    },
-                };
+                // Semantic reports save the v2 definition document verbatim;
+                // legacy reports keep their existing v1 shape.
+                const reportConfig = isSemantic
+                    ? {
+                          label: result.value.name,
+                          is_public: result.value.isPublic,
+                          detail: semanticDefinition,
+                      }
+                    : {
+                          label: result.value.name,
+                          is_public: result.value.isPublic,
+                          detail: {
+                              mainTable: selectedTable,
+                              columns: selectedColumns,
+                              joins: joins,
+                              filters: filterCriteria,
+                              sorting: sortCriteria,
+                              grouping: groupingConfig.enabled
+                                  ? groupingConfig
+                                  : null,
+                              isGrouped: groupingConfig.enabled,
+                              customCalculatedFields: customCalculatedFields,
+                              customUrls: customUrls,
+                              unique: uniqueFieldConfig,
+                          },
+                      };
 
                 let saveResult;
                 if (isExistingReport) {