@visns-studio/visns-components 6.1.8 → 6.2.1

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 = {
@@ -1204,224 +1752,56 @@ const GenericReportImproved = ({
         return icons[iconName] || icons.chart;
     };
 
-    // Show comprehensive help guide
-    const showGuidedHelp = () => {
+    /* ---------------------------------------------------------------- */
+    /* Guided help                                                       */
+    /* ---------------------------------------------------------------- */
+
+    /**
+     * One heading style for both guides, so the legacy and semantic help read
+     * as the same help system. `icon` is a key of `getIcon`.
+     */
+    const helpHeading = (icon, color, title) =>
+        `<h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid ${color}; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">${getIcon(
+            icon,
+            color,
+            16
+        )}${title}</h3>`;
+
+    /**
+     * A tinted panel with a bulleted body. Passing `items` as a string renders
+     * it as a paragraph instead, for the short explanatory panels.
+     */
+    const helpPanel = ({ bg, border, text, title, icon, items }) => {
+        const body = Array.isArray(items)
+            ? `<ul style="margin: 0; padding-left: 16px; color: ${text};">${items
+                  .map((item) => `<li>${item}</li>`)
+                  .join('')}</ul>`
+            : `<p style="margin: 0; color: ${text};">${items}</p>`;
+
+        return `
+            <div style="background: ${bg}; border: 1px solid ${border}; border-radius: 8px; padding: 12px; margin-bottom: 12px;">
+                ${
+                    title
+                        ? `<h4 style="color: ${border}; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">${
+                              icon ? getIcon(icon, border, 14) : ''
+                          }${title}</h4>`
+                        : ''
+                }
+                ${body}
+            </div>`;
+    };
+
+    /** Shared SweetAlert2 options so both guides open the same way. */
+    const showHelpModal = (titleIcon, titleText, sections) =>
         Swal.fire({
             title: `<div style="display: flex; align-items: center; justify-content: center; gap: 8px;">${getIcon(
-                'chart',
+                titleIcon,
                 '#3b82f6',
                 24
-            )}Complete Report Builder Guide</div>`,
-            html: `
-                <div style="text-align: left; font-size: 13px; line-height: 1.5; color: #374151; max-height: 70vh; overflow-y: auto;">
-                    
-                    <!-- Quick Start Section -->
-                    <div style="margin-bottom: 24px;">
-                        <h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid #3b82f6; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">
-                            ${getIcon('rocket', '#3b82f6', 16)}
-                            Getting Started
-                        </h3>
-                        
-                        <div style="background: #f0f9ff; border-left: 4px solid #3b82f6; padding: 12px; margin-bottom: 12px;">
-                            <h4 style="color: #1e40af; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('file', '#1e40af', 14)}
-                                Option 1: Use Saved Reports (Recommended)
-                            </h4>
-                            <p style="margin: 0 0 8px 0;">Click the "Templates" button to access pre-built reports for common needs like client lists, recent orders, or financial summaries.</p>
-                            <p style="margin: 0; font-style: italic; color: #1e40af;">Perfect for beginners and quick results!</p>
-                        </div>
-
-                        <div style="background: #f9fafb; border-left: 4px solid #6b7280; padding: 12px;">
-                            <h4 style="color: #374151; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('cogs', '#374151', 14)}
-                                Option 2: Build Custom Report
-                            </h4>
-                            <p style="margin: 0;">Follow the 5-step wizard below to create exactly what you need.</p>
-                        </div>
-                    </div>
-
-                    <!-- Step-by-Step Guide -->
-                    <div style="margin-bottom: 24px;">
-                        <h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid #10b981; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">
-                            ${getIcon('list', '#10b981', 16)}
-                            5-Step Report Creation
-                        </h3>
-                        
-                        <!-- Step 1 -->
-                        <div style="background: #ecfdf5; border: 1px solid #10b981; border-radius: 8px; padding: 12px; margin-bottom: 12px;">
-                            <h4 style="color: #047857; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('database', '#047857', 14)}
-                                Step 1: Choose Your Data Source
-                            </h4>
-                            <ul style="margin: 0; padding-left: 16px; color: #065f46;">
-                                <li>Select the main table (e.g., Clients, Orders, Invoices)</li>
-                                <li>This becomes the foundation of your report</li>
-                                <li>Look for the table icon to identify data types</li>
-                            </ul>
-                        </div>
-
-                        <!-- Step 2 -->
-                        <div style="background: #eff6ff; border: 1px solid #3b82f6; border-radius: 8px; padding: 12px; margin-bottom: 12px;">
-                            <h4 style="color: #1e40af; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('columns', '#1e40af', 14)}
-                                Step 2: Select Columns
-                            </h4>
-                            <ul style="margin: 0; padding-left: 16px; color: #1e3a8a;">
-                                <li>Check the boxes for data you want to see</li>
-                                <li>Drag columns to reorder them</li>
-                                <li>Use "Select All" for comprehensive reports</li>
-                                <li>Preview shows how your data will look</li>
-                            </ul>
-                        </div>
-
-                        <!-- Step 3 -->
-                        <div style="background: #fef3c7; border: 1px solid #f59e0b; border-radius: 8px; padding: 12px; margin-bottom: 12px;">
-                            <h4 style="color: #92400e; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('link', '#92400e', 14)}
-                                Step 3: Add Relationships (Optional)
-                            </h4>
-                            <ul style="margin: 0; padding-left: 16px; color: #92400e;">
-                                <li>Connect related data (e.g., add customer names to invoices)</li>
-                                <li>We suggest common relationships automatically</li>
-                                <li>Click "Add Relationship" to connect more tables</li>
-                                <li>This enriches your report with additional context</li>
-                            </ul>
-                        </div>
-
-                        <!-- Step 4 -->
-                        <div style="background: #fdf2f8; border: 1px solid #ec4899; border-radius: 8px; padding: 12px; margin-bottom: 12px;">
-                            <h4 style="color: #be185d; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('filter', '#be185d', 14)}
-                                Step 4: Apply Filters (Optional)
-                            </h4>
-                            <ul style="margin: 0; padding-left: 16px; color: #be185d;">
-                                <li>Narrow down results (e.g., "Active clients only")</li>
-                                <li>Use AND/OR logic for complex conditions</li>
-                                <li>Group filters for advanced filtering</li>
-                                <li>Great for date ranges, status filters, etc.</li>
-                            </ul>
-                        </div>
-
-                        <!-- Step 5 -->
-                        <div style="background: #f3e8ff; border: 1px solid #8b5cf6; border-radius: 8px; padding: 12px;">
-                            <h4 style="color: #7c3aed; margin: 0 0 8px 0; font-size: 14px; display: flex; align-items: center; gap: 6px;">
-                                ${getIcon('download', '#7c3aed', 14)}
-                                Step 5: Generate & Export
-                            </h4>
-                            <ul style="margin: 0; padding-left: 16px; color: #7c3aed;">
-                                <li>Click "Generate Report" to see your data</li>
-                                <li>Review and refine as needed</li>
-                                <li>Export as Excel, CSV, or PDF</li>
-                                <li>Save the report template for future use</li>
-                            </ul>
-                        </div>
-                    </div>
-
-                    <!-- Pro Tips Section -->
-                    <div style="margin-bottom: 20px;">
-                        <h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid #f59e0b; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">
-                            ${getIcon('star', '#f59e0b', 16)}
-                            Pro Tips
-                        </h3>
-                        
-                        <div style="background: #fffbeb; border: 1px solid #f59e0b; border-radius: 8px; padding: 12px;">
-                            <ul style="margin: 0; padding-left: 16px; color: #92400e;">
-                                <li><strong>Start Simple:</strong> Begin with basic reports, then add complexity</li>
-                                <li><strong>Use Previews:</strong> Check the preview before generating large reports</li>
-                                <li><strong>Save Templates:</strong> Save frequently used reports as templates</li>
-                                <li><strong>Date Filters:</strong> Use date ranges for better performance</li>
-                                <li><strong>Column Limits:</strong> Too many columns can slow down reports</li>
-                            </ul>
-                        </div>
-                    </div>
-
-                    <!-- Common Use Cases -->
-                    <div style="margin-bottom: 20px;">
-                        <h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid #10b981; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">
-                            ${getIcon('lightbulb', '#10b981', 16)}
-                            Common Report Examples
-                        </h3>
-                        
-                        <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 8px;">
-                            <div style="background: #f0fdf4; border: 1px solid #22c55e; border-radius: 6px; padding: 8px;">
-                                <strong style="color: #15803d;">${getIcon(
-                                    'users',
-                                    '#15803d',
-                                    12
-                                )}Client List:</strong>
-                                <br><small style="color: #16a34a;">Clients table + Contact details</small>
-                            </div>
-                            <div style="background: #eff6ff; border: 1px solid #3b82f6; border-radius: 6px; padding: 8px;">
-                                <strong style="color: #1d4ed8;">${getIcon(
-                                    'cart',
-                                    '#1d4ed8',
-                                    12
-                                )}Recent Orders:</strong>
-                                <br><small style="color: #2563eb;">Orders + Customer names + Date filter</small>
-                            </div>
-                            <div style="background: #fef3c7; border: 1px solid #f59e0b; border-radius: 6px; padding: 8px;">
-                                <strong style="color: #d97706;">${getIcon(
-                                    'money',
-                                    '#d97706',
-                                    12
-                                )}Financial Summary:</strong>
-                                <br><small style="color: #f59e0b;">Invoices + Payments + Date grouping</small>
-                            </div>
-                            <div style="background: #fdf2f8; border: 1px solid #ec4899; border-radius: 6px; padding: 8px;">
-                                <strong style="color: #db2777;">${getIcon(
-                                    'tasks',
-                                    '#db2777',
-                                    12
-                                )}Active Projects:</strong>
-                                <br><small style="color: #ec4899;">Projects + Status filter + Team members</small>
-                            </div>
-                        </div>
-                    </div>
-
-                    <!-- Troubleshooting -->
-                    <div>
-                        <h3 style="color: #1f2937; margin: 0 0 12px 0; font-size: 16px; border-bottom: 2px solid #dc2626; padding-bottom: 6px; display: flex; align-items: center; gap: 8px;">
-                            ${getIcon('settings', '#dc2626', 16)}
-                            Common Issues
-                        </h3>
-                        
-                        <div style="background: #fef2f2; border: 1px solid #dc2626; border-radius: 8px; padding: 12px;">
-                            <div style="margin-bottom: 8px;">
-                                <strong style="color: #dc2626;">${getIcon(
-                                    'clock',
-                                    '#dc2626',
-                                    12
-                                )}Report too slow?</strong>
-                                <span style="color: #991b1b;"> Add date filters or reduce columns</span>
-                            </div>
-                            <div style="margin-bottom: 8px;">
-                                <strong style="color: #dc2626;">${getIcon(
-                                    'question',
-                                    '#dc2626',
-                                    12
-                                )}Missing data?</strong>
-                                <span style="color: #991b1b;"> Check relationships and join conditions</span>
-                            </div>
-                            <div style="margin-bottom: 8px;">
-                                <strong style="color: #dc2626;">${getIcon(
-                                    'warning',
-                                    '#dc2626',
-                                    12
-                                )}Export failing?</strong>
-                                <span style="color: #991b1b;"> Try smaller date ranges or fewer rows</span>
-                            </div>
-                            <div>
-                                <strong style="color: #dc2626;">${getIcon(
-                                    'eye',
-                                    '#dc2626',
-                                    12
-                                )}No data showing?</strong>
-                                <span style="color: #991b1b;"> Review your filter conditions</span>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            `,
+            )}${titleText}</div>`,
+            html: `<div style="text-align: left; font-size: 13px; line-height: 1.5; color: #374151; max-height: 70vh; overflow-y: auto;">${sections.join(
+                '<div style="height: 12px;"></div>'
+            )}</div>`,
             width: 800,
             confirmButtonText: 'Close',
             confirmButtonColor: '#6b7280',
@@ -1432,22 +1812,351 @@ const GenericReportImproved = ({
                 htmlContainer: 'help-content-scrollable',
             },
         });
-    };
+
+    /**
+     * Help for the semantic wizard: the user picks subjects, related areas and
+     * details by their business names, so the guide never mentions a table, a
+     * column or a join.
+     */
+    const showSemanticGuidedHelp = () =>
+        showHelpModal('chart', 'Report Builder Guide', [
+            helpHeading('rocket', '#3b82f6', 'Getting started') +
+                helpPanel({
+                    bg: '#f0f9ff',
+                    border: '#3b82f6',
+                    text: '#1e3a8a',
+                    icon: 'file',
+                    title: 'Open a report someone already built',
+                    items: [
+                        'The builder opens on "Choose a Starting Point"',
+                        'Click any saved report to open it, change it and run it',
+                        'A padlock means only you can see it; a globe means everyone can',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f9fafb',
+                    border: '#6b7280',
+                    text: '#374151',
+                    icon: 'cogs',
+                    title: 'Build a new one',
+                    items: [
+                        'Click "Create New Report" and work through the six steps',
+                        'Only two things are compulsory: what the report is about, and at least one detail to show',
+                        'Related information, filters and grouping can all be skipped',
+                    ],
+                }),
+
+            helpHeading('list', '#10b981', 'The six steps') +
+                helpPanel({
+                    bg: '#ecfdf5',
+                    border: '#10b981',
+                    text: '#065f46',
+                    icon: 'database',
+                    title: '1. Choose Your Subject',
+                    items: [
+                        'Each card is a kind of record your practice keeps, in plain English',
+                        'The card tells you how many details and related areas it has',
+                        'Pick the one you want one row per — for example one row per client',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#eff6ff',
+                    border: '#3b82f6',
+                    text: '#1e3a8a',
+                    icon: 'link',
+                    title: '2. Add Related Data (optional)',
+                    items: [
+                        'Each card is an area already connected to your subject — nothing to set up',
+                        'Click one to make its details available at the next step',
+                        'Once added, areas connected to that one appear too, up to three steps out',
+                        'An area marked "many per record" can repeat a record across several rows',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f0fdf4',
+                    border: '#22c55e',
+                    text: '#166534',
+                    icon: 'columns',
+                    title: '3. Choose Information',
+                    items: [
+                        'Details are listed under the area they come from, then sorted into Details, Amounts &amp; numbers, Dates, and Status &amp; yes/no',
+                        'Tick anything you want as a column',
+                        'Each ticked detail gets a "Show as" picker — see Totals and counts below',
+                        '"Columns in your report" lists your choices left to right; use Up, Down and the X to reorder or remove them',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#fdf2f8',
+                    border: '#ec4899',
+                    text: '#9d174d',
+                    icon: 'filter',
+                    title: '4. Filter Results (optional)',
+                    items: [
+                        'Add a condition, choose a detail, then a plain-English test: is, is not, contains, is between, is more than, is blank, is any of, and so on',
+                        'The value box matches the detail — a date picker for dates, a list of choices for a status',
+                        'Switch a group between "all of these" and "any of these"',
+                        'Add a nested group to mix the two, e.g. active AND (has email OR has phone)',
+                        'No conditions means every record is included',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#fef3c7',
+                    border: '#f59e0b',
+                    text: '#92400e',
+                    icon: 'database',
+                    title: '5. Group &amp; Order (optional)',
+                    items: [
+                        'Tick a column to break the results into sections by its value',
+                        'Only plain columns can be grouped — a summarised column is the answer, not the heading',
+                        'Add one or more sorts to control the row order, each A to Z / low to high or the reverse',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f3e8ff',
+                    border: '#8b5cf6',
+                    text: '#6b21a8',
+                    icon: 'eye',
+                    title: '6. Preview &amp; Save',
+                    items: [
+                        'Answer any run-time questions, then click "Run report"',
+                        'Results appear 10, 25, 50 or 100 rows at a time',
+                        'Save the report, and export the results when they look right',
+                    ],
+                }),
+
+            helpHeading('money', '#0891b2', 'Totals, counts and averages') +
+                helpPanel({
+                    bg: '#ecfeff',
+                    border: '#0891b2',
+                    text: '#155e75',
+                    items: [
+                        '"Show as" is set to <strong>Value</strong> by default, which simply lists the detail',
+                        'Change it to <strong>Total</strong>, <strong>Average</strong>, <strong>Lowest</strong> or <strong>Highest</strong> on amounts and numbers, <strong>Earliest</strong> or <strong>Latest</strong> on dates, and <strong>Count</strong> on anything',
+                        'As soon as one column is summarised, the report collapses to one row per combination of the plain columns you kept',
+                        'So for totals by adviser: choose Clients, show the adviser’s name as Value and the fee amount as Total — you get one row per adviser',
+                        'If you also tick grouping at step 5 while a column is summarised, tick <em>every</em> plain column, or the report will be refused',
+                    ],
+                }),
+
+            helpHeading('question', '#7c3aed', 'Reports that ask a question each time') +
+                helpPanel({
+                    bg: '#f5f3ff',
+                    border: '#7c3aed',
+                    text: '#5b21b6',
+                    items: [
+                        'On any condition, tick "Ask me for this each time I run it"',
+                        'The value is left out of the saved report and asked for instead, under "Before we run this report"',
+                        'Give each question a clear name — that wording is what everyone else will see',
+                        'Untick "Must be answered" to make a question optional',
+                        'Ideal for anything that changes week to week, such as a date range',
+                    ],
+                }),
+
+            helpHeading('users', '#059669', 'Saving and sharing') +
+                helpPanel({
+                    bg: '#ecfdf5',
+                    border: '#059669',
+                    text: '#065f46',
+                    items: [
+                        '"Save report" asks for a name and whether to make it public',
+                        'Private reports (padlock) are yours; public ones (globe) are visible to other users',
+                        'Opening a saved report and saving again updates it — use the copy option to keep the original',
+                        'A saved report stores the recipe, not the results, so it always runs against today’s data',
+                    ],
+                }),
+
+            helpHeading('download', '#b45309', 'Exporting') +
+                helpPanel({
+                    bg: '#fffbeb',
+                    border: '#b45309',
+                    text: '#92400e',
+                    items: [
+                        'Run the report first, then choose Excel, CSV or PDF from "Export as"',
+                        'The export covers the whole report, not just the page on screen',
+                        'PDF suits short reports; use Excel or CSV for long ones',
+                    ],
+                }),
+
+            helpHeading('warning', '#dc2626', 'Good to know') +
+                helpPanel({
+                    bg: '#fef2f2',
+                    border: '#dc2626',
+                    text: '#991b1b',
+                    items: [
+                        'Deleted records are left out of reports entirely — they are missing from the rows, and from every count and total',
+                        'Adding a "many per record" area can multiply your rows; summarise it instead to keep one row per record',
+                        'Nothing shown at all? Check your conditions at step 4 — one condition too many is the usual cause',
+                        'If the report is refused, the message on screen names the detail that caused it',
+                    ],
+                }),
+        ]);
+
+    /**
+     * Help for the legacy table/column wizard, used when the newer report
+     * engine is not available.
+     */
+    const showLegacyGuidedHelp = () =>
+        showHelpModal('chart', 'Complete Report Builder Guide', [
+            helpHeading('rocket', '#3b82f6', 'Getting Started') +
+                helpPanel({
+                    bg: '#f0f9ff',
+                    border: '#3b82f6',
+                    text: '#1e3a8a',
+                    icon: 'file',
+                    title: 'Option 1: Start from a saved report (recommended)',
+                    items: [
+                        'The builder opens on "Choose a Starting Point"',
+                        'Click any saved report to open it and adjust it',
+                        'A padlock means only you can see it; a globe means everyone can',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f9fafb',
+                    border: '#6b7280',
+                    text: '#374151',
+                    icon: 'cogs',
+                    title: 'Option 2: Build a custom report',
+                    items: [
+                        'Click "Create New Report" and follow the six steps below',
+                    ],
+                }),
+
+            helpHeading('list', '#10b981', 'Six steps to a report') +
+                helpPanel({
+                    bg: '#ecfdf5',
+                    border: '#10b981',
+                    text: '#065f46',
+                    icon: 'database',
+                    title: 'Step 1: Select Your Data',
+                    items: [
+                        'Choose the main data source your report is about',
+                        'This becomes the foundation of the report',
+                        'You can bring in related data at the next step',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#fef3c7',
+                    border: '#f59e0b',
+                    text: '#92400e',
+                    icon: 'link',
+                    title: 'Step 2: Add Related Data (optional)',
+                    items: [
+                        'Review the connections suggested for you',
+                        'Connect the ones that add value, e.g. customer names on invoices',
+                        'Connected data provides extra fields at the next step',
+                        'Skip this step if the main data source has everything you need',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#eff6ff',
+                    border: '#3b82f6',
+                    text: '#1e3a8a',
+                    icon: 'columns',
+                    title: 'Step 3: Choose Information',
+                    items: [
+                        'Tick the fields you want to see, from your main data source and anything you connected',
+                        'Fields are grouped by category to make them easier to find',
+                        'Use "Select All Visible" or "Clear All" to work quickly',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#fdf2f8',
+                    border: '#ec4899',
+                    text: '#9d174d',
+                    icon: 'filter',
+                    title: 'Step 4: Filter Results (optional)',
+                    items: [
+                        'Narrow the results down, e.g. active clients only',
+                        'Combine conditions with AND/OR logic',
+                        'Group conditions together for more involved rules',
+                        'Great for date ranges and status filters',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f0fdf4',
+                    border: '#22c55e',
+                    text: '#166534',
+                    icon: 'database',
+                    title: 'Step 5: Group Configuration (optional)',
+                    items: [
+                        'Turn on grouping to split the report into sections',
+                        'Choose the field to group by, e.g. status or category',
+                        'Set the group display and styling options',
+                        'Skip this step for a plain table',
+                    ],
+                }) +
+                helpPanel({
+                    bg: '#f3e8ff',
+                    border: '#8b5cf6',
+                    text: '#6b21a8',
+                    icon: 'download',
+                    title: 'Step 6: Preview &amp; Save',
+                    items: [
+                        'Click "Generate Report" to see your data',
+                        'Review the results and refine as needed',
+                        'Save the report so you can run it again later',
+                        'Click "Export" to download the results as an Excel file',
+                    ],
+                }),
+
+            helpHeading('star', '#f59e0b', 'Pro Tips') +
+                helpPanel({
+                    bg: '#fffbeb',
+                    border: '#f59e0b',
+                    text: '#92400e',
+                    items: [
+                        '<strong>Start simple:</strong> begin with a basic report, then add to it',
+                        '<strong>Save before exporting:</strong> an export needs the report to have a name',
+                        '<strong>Save your work:</strong> a saved report can be run again any time against current data',
+                        '<strong>Date filters:</strong> narrowing the dates keeps big reports fast',
+                        '<strong>Field limits:</strong> too many fields can slow a report down',
+                    ],
+                }),
+
+            helpHeading('settings', '#dc2626', 'Common Issues') +
+                helpPanel({
+                    bg: '#fef2f2',
+                    border: '#dc2626',
+                    text: '#991b1b',
+                    items: [
+                        '<strong>Report too slow?</strong> Add date filters or reduce the number of fields',
+                        '<strong>Missing data?</strong> Check the connections you added at step 2',
+                        '<strong>Export failing?</strong> Try a smaller date range or fewer rows',
+                        '<strong>No data showing?</strong> Review your filter conditions',
+                    ],
+                }),
+        ]);
+
+    /** The guide matches whichever wizard the user is actually looking at. */
+    const showGuidedHelp = () =>
+        isSemantic ? showSemanticGuidedHelp() : showLegacyGuidedHelp();
 
     // 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
-        const hasSeenHelp = localStorage.getItem('reportBuilder_hasSeenHelp');
+        // Show help on first load. The two wizards keep separate flags: users
+        // who already dismissed the legacy guide have never seen the semantic
+        // one, and it describes a different set of steps.
+        const helpSeenKey = isSemantic
+            ? 'reportBuilder_hasSeenSemanticHelp'
+            : 'reportBuilder_hasSeenHelp';
+        const hasSeenHelp = localStorage.getItem(helpSeenKey);
         if (!hasSeenHelp) {
             setTimeout(() => {
                 showGuidedHelp();
-                localStorage.setItem('reportBuilder_hasSeenHelp', 'true');
+                localStorage.setItem(helpSeenKey, '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 +2231,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 +2242,7 @@ const GenericReportImproved = ({
             executeReport();
         }
     }, [
+        isSemantic,
         currentWizardStep,
         selectedTable,
         selectedColumns.length,
@@ -1539,6 +2250,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 +2469,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 +2479,7 @@ const GenericReportImproved = ({
 
     // Wizard navigation
     const goToNextStep = () => {
-        if (currentWizardStep < wizardSteps.length - 1) {
+        if (currentWizardStep < activeWizardSteps.length - 1) {
             setCurrentWizardStep(currentWizardStep + 1);
         }
     };
@@ -1744,6 +2492,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 +2580,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 +3755,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 +3800,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 +4241,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 +4310,7 @@ const GenericReportImproved = ({
                                                     </span>
                                                 </div>
                                             </div>
-                                            {reportMainTable && (
+                                            {reportSubject && (
                                                 <div
                                                     className={
                                                         styles.reportTableInfo
@@ -3517,9 +4330,7 @@ const GenericReportImproved = ({
                                                                     'middle',
                                                             }}
                                                         />
-                                                        {formatName(
-                                                            reportMainTable
-                                                        )}
+                                                        {reportSubject}
                                                     </span>
                                                 </div>
                                             )}
@@ -3571,14 +4382,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 +4507,7 @@ const GenericReportImproved = ({
                             </button>
                         )}
 
-                        {currentWizardStep === wizardSteps.length - 1 ? (
+                        {currentWizardStep === activeWizardSteps.length - 1 ? (
                             <button
                                 type="button"
                                 className={`${styles.btn} ${styles.btnStartAgain}`}
@@ -3720,8 +4531,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 +8251,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 +8292,7 @@ const GenericReportImproved = ({
                             saveAs
                                 ? `${reportName} (Copy)`
                                 : reportName ||
-                                      `${formatName(
-                                          selectedTable
-                                      )} Report - ${moment().format(
+                                      `${subjectName} Report - ${moment().format(
                                           'YYYY-MM-DD'
                                       )}`
                         )}"
@@ -7416,24 +8329,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) {