@visns-studio/visns-components 6.2.0 → 6.3.0

package/package.json

@@ -91,7 +91,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.2.0",
+    "version": "6.3.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/generic/GenericFormBuilder.jsx

@@ -40,7 +40,9 @@ import {
     ChevronRight,
     Copy,
     List,
+    HelpCircle,
 } from 'lucide-react';
+import Swal from 'sweetalert2';
 import { confirmDialog } from '../utils/ConfirmDialog';
 
 import 'react-toggle/style.css';
@@ -166,6 +168,24 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
      * tab itself has already replaced.
      */
     const expectedDetailHashRef = useRef(null);
+
+    /**
+     * The `{label, detail}` the server is believed to hold, as a comparable
+     * string.
+     *
+     * Every authoring action on this screen — adding a question, rewording an
+     * option, changing a size — only moves React state. Nothing reaches the
+     * server until the template itself is saved, and until this ref existed
+     * there was no way to tell "on screen" from "stored": a tab could be closed
+     * on an afternoon's work and say nothing about it.
+     *
+     * Null until the first load lands. Before that there is no baseline, and
+     * everything would compare as changed.
+     */
+    const savedSnapshotRef = useRef(null);
+    const [unsavedChanges, setUnsavedChanges] = useState(false);
+    /** Bumped whenever the baseline moves, so the comparison below re-runs. */
+    const [savedBaselineTick, setSavedBaselineTick] = useState(0);
     const lockEnabled = Boolean(optimisticLock);
     const lockSchemaVersion =
         optimisticLock?.schemaVersion ?? DEFAULT_LOCK_SCHEMA_VERSION;
@@ -1395,6 +1415,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             (!field.options || field.options.length === 0)
         ) {
             errors.push('Please add options for the dropdown.');
+        } else if (
+            /**
+             * A checkbox with no options renders as a bare label with nothing
+             * to tick. Harmless-looking in the builder, and fatal in the field:
+             * marked required, it cannot be answered, so the form it belongs to
+             * can never be submitted. Dropdowns have always been held to this;
+             * checkboxes were simply missed.
+             */
+            field.type === 'checkbox' &&
+            (!field.options || field.options.length === 0)
+        ) {
+            errors.push(
+                'Please add at least one option for the checkbox — a checkbox with no options cannot be answered.'
+            );
         } else if (
             field.type === 'table_text' &&
             (!field.options || field.options.length === 0)
@@ -1812,6 +1846,34 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         );
     };
 
+    /** The comparable form of the two things this screen actually stores. */
+    const snapshotOf = (label, detail) =>
+        JSON.stringify({ label: label ?? '', detail: detail ?? [] });
+
+    /**
+     * Re-anchor the unsaved-changes baseline on what the server now holds.
+     *
+     * Takes a partial: the sort endpoint writes `detail` alone and leaves the
+     * label as it was, so rebuilding the whole baseline from the current
+     * on-screen `data` would quietly adopt an unsaved rename as "stored".
+     */
+    const markSaved = ({ label, detail } = {}) => {
+        const previous = savedSnapshotRef.current
+            ? JSON.parse(savedSnapshotRef.current)
+            : {};
+
+        savedSnapshotRef.current = snapshotOf(
+            label === undefined ? previous.label : label,
+            detail === undefined ? previous.detail : detail
+        );
+
+        // Never `setUnsavedChanges(false)` directly: a partial save can leave
+        // something else still unsaved. Re-ordering writes `detail` and not the
+        // label, so declaring the screen clean here would lose a pending
+        // rename. Let the one comparison decide.
+        setSavedBaselineTick((tick) => tick + 1);
+    };
+
     /**
      * "Somebody else got here first", in the only words that help.
      *
@@ -1875,6 +1937,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
 
                     if (res.data.error === '') {
                         await rememberDetailHash(data.id, savedDetail);
+                        markSaved({
+                            label: data.label,
+                            detail: savedDetail,
+                        });
 
                         toast.success(
                             "You have successfully updated the form's detail."
@@ -1910,7 +1976,31 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                     return;
                 }
 
+                /**
+                 * Suppressing the shared handler's toast made this branch the
+                 * only voice the user has, so it must never be silent. It used
+                 * to `return` here, which turned an expired session (401
+                 * `Unauthenticated.`) — or any error body carrying neither
+                 * `errors` nor `message` — into a save that looked like it had
+                 * worked: nothing stored, and nothing said about it.
+                 */
                 if (err?.response) {
+                    const status = err.response.status;
+                    const expired =
+                        status === 401 || message === 'Unauthenticated.';
+
+                    toast.error(
+                        <div>
+                            <strong>Nothing was saved.</strong>{' '}
+                            {expired
+                                ? 'Your session has expired. Sign in again in another tab, then come back and save — your changes are still on screen.'
+                                : `The server refused the save${
+                                      status ? ` (error ${status})` : ''
+                                  }. Your changes are still on screen — try again, and report this if it keeps happening.`}
+                        </div>,
+                        { autoClose: false }
+                    );
+
                     return;
                 }
             }
@@ -1932,6 +2022,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             // The version this tab is editing from. Everything the guard does
             // is measured against this moment.
             await rememberDetailHash(res.data?.id, res.data?.detail);
+            markSaved({
+                label: res.data?.label,
+                detail: res.data?.detail,
+            });
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -1959,6 +2053,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             // here — but leaving the hash behind would make the next Save
             // report a collision this tab caused itself.
             await rememberDetailHash(data.id, savedDetail);
+
+            // Re-ordering is the one authoring action that reaches the server
+            // on its own, so the unsaved-changes baseline has to follow it too.
+            markSaved({ detail: savedDetail });
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -1990,6 +2088,297 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         fetchRoles();
     }, []);
 
+    /**
+     * Is what is on screen different from what is stored?
+     *
+     * Compared against the baseline rather than tracked per-action, so it
+     * cannot drift: undoing a change by hand correctly reports "all changes
+     * saved" again, and no authoring path can forget to raise the flag.
+     */
+    useEffect(() => {
+        if (savedSnapshotRef.current === null) {
+            return;
+        }
+
+        setUnsavedChanges(
+            snapshotOf(data.label, data.detail) !== savedSnapshotRef.current
+        );
+    }, [data, savedBaselineTick]);
+
+    /**
+     * The browser's own "leave site?" prompt, and only while there is something
+     * to lose. Last line of defence for the failure this screen is prone to: a
+     * question window's button reads as final, so a template can be closed in
+     * the belief that its questions were filed.
+     */
+    useEffect(() => {
+        if (!unsavedChanges) {
+            return undefined;
+        }
+
+        const warnBeforeLeaving = (event) => {
+            event.preventDefault();
+            event.returnValue = '';
+
+            return '';
+        };
+
+        window.addEventListener('beforeunload', warnBeforeLeaving);
+
+        return () =>
+            window.removeEventListener('beforeunload', warnBeforeLeaving);
+    }, [unsavedChanges]);
+
+    /* ---------------------------------------------------------------- */
+    /* Guided help                                                       */
+    /* ---------------------------------------------------------------- */
+
+    /**
+     * Inline SVG for the guide's section headings. SweetAlert2 takes an HTML
+     * string, so the lucide components used elsewhere in this file cannot be
+     * rendered here — these mirror the same icons at the same weight.
+     */
+    const helpIcon = (name, color) => {
+        const open = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="${color}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align: middle; display: inline-block;">`;
+        const paths = {
+            rocket: '<path d="M12 2c5 3 8 5 8 9a6 6 0 1 1-12 0c0-4 3-6 8-9Z"/><path d="m16 6-4 14-4-14"/><circle cx="12" cy="12" r="2"/>',
+            list: '<line x1="8" x2="21" y1="6" y2="6"/><line x1="8" x2="21" y1="12" y2="12"/><line x1="8" x2="21" y1="18" y2="18"/><line x1="3" x2="3.01" y1="6" y2="6"/><line x1="3" x2="3.01" y1="12" y2="12"/><line x1="3" x2="3.01" y1="18" y2="18"/>',
+            layers: '<path d="m12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83Z"/><path d="m22 12.5-9.17 4.16a2 2 0 0 1-1.66 0L2 12.5"/>',
+            type: '<polyline points="4 7 4 4 20 4 20 7"/><line x1="9" x2="15" y1="20" y2="20"/><line x1="12" x2="12" y1="4" y2="20"/>',
+            settings:
+                '<path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/>',
+            table: '<path d="M12 3v18"/><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M3 9h18"/><path d="M3 15h18"/>',
+            branch: '<line x1="6" x2="6" y1="3" y2="15"/><circle cx="18" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/>',
+            flag: '<path d="M4 15s1-1 4-1 5 2 8 2 4-1 4-1V3s-1 1-4 1-5-2-8-2-4 1-4 1z"/><line x1="4" x2="4" y1="22" y2="15"/>',
+            save: '<path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/>',
+            help: '<circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><path d="M12 17h.01"/>',
+        };
+        return `${open}${paths[name] || paths.help}</svg>`;
+    };
+
+    /** One heading style for every section of the guide. */
+    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;">${helpIcon(
+            icon,
+            color
+        )}${title}</h3>`;
+
+    /** A tinted panel with a bulleted body, optionally titled. */
+    const helpPanel = ({ bg, border, text, title, items }) => `
+        <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;">${title}</h4>`
+                    : ''
+            }
+            <ul style="margin: 0; padding-left: 16px; color: ${text};">${items
+                .map((item) => `<li>${item}</li>`)
+                .join('')}</ul>
+        </div>`;
+
+    /**
+     * The end-user guide to building a template. Sections that describe an
+     * opt-in feature are only included when this app actually switched that
+     * feature on, so nobody is told about a control they will never see.
+     */
+    const showGuidedHelp = () => {
+        const sections = [
+            helpHeading('rocket', '#3b82f6', 'What this screen is') +
+                helpPanel({
+                    bg: '#f0f9ff',
+                    border: '#3b82f6',
+                    text: '#1e3a8a',
+                    items: [
+                        'This is the list of questions people will answer — for example a client review checklist',
+                        '<strong>Edit</strong> shows one compact row per question, with a summary of how it is set up',
+                        '<strong>Preview</strong> shows the form the way the person filling it in will see it',
+                        '<strong>Sections</strong> shows a strip of shortcuts, one per section; click one to jump to it',
+                        'Once there are more than five questions, a search box appears — matching questions stay bright and the rest dim',
+                    ],
+                }),
+
+            helpHeading('list', '#10b981', 'Adding and arranging questions') +
+                helpPanel({
+                    bg: '#ecfdf5',
+                    border: '#10b981',
+                    text: '#065f46',
+                    items: dynamicFields
+                        ? [
+                              'This template builds its own questions automatically, so there is no "Add Field" button',
+                              'Use the pencil to adjust a question, and the grip handle on the left to drag it into a new position',
+                          ]
+                        : [
+                              '<strong>Add Field</strong> (bottom right) opens the question window',
+                              'The pencil edits a question, the copy icon duplicates it, the bin deletes it',
+                              'Duplicating a Section copies the section and every question inside it',
+                              'Drag the grip handle on the left to move a question; the up/down arrows let you type an exact position instead',
+                              'Deleting a question also clears any "show only when" rule that pointed at it, and tells you how many were cleared',
+                          ],
+                }),
+
+            helpHeading('layers', '#7c3aed', 'Sections and headings') +
+                helpPanel({
+                    bg: '#f5f3ff',
+                    border: '#7c3aed',
+                    text: '#5b21b6',
+                    items: [
+                        'Add a question of type <strong>Section</strong> to start a new part of the form',
+                        'Everything after a Section belongs to it, until the next Section starts',
+                        'Questions before the first Section are listed under "Before first section"',
+                        'Click the arrow on a Section row to collapse or expand it while you work',
+                        '<strong>Heading</strong> is simpler — just a title on the page, with no grouping',
+                        '<strong>Plain Text</strong> is a block of formatted wording, for instructions or a declaration',
+                    ],
+                }),
+
+            helpHeading('type', '#0891b2', 'The kinds of question you can add') +
+                helpPanel({
+                    bg: '#ecfeff',
+                    border: '#0891b2',
+                    text: '#155e75',
+                    items: [
+                        '<strong>Typed in:</strong> Text (one line), Textarea (several lines), Number',
+                        '<strong>Chosen from a list:</strong> Dropdown, Checkbox, Toggle (a yes/no switch)',
+                        '<strong>Dates and times:</strong> Date, Date &amp; Time, Time',
+                        '<strong>Attached or drawn:</strong> File, Image, Video Upload, Signature, Canvas',
+                        '<strong>Grids:</strong> Table (Radio) and Table (Custom) — see below',
+                        '<strong>Layout only:</strong> Section, Heading, Plain Text',
+                        `<strong>Filled from your system:</strong> Dynamic Data pulls in a detail the system already holds${
+                            dynamicDropdowns && dynamicDropdowns.length > 0
+                                ? ', and Dynamic Dropdown offers a list your system maintains'
+                                : ''
+                        }`,
+                    ],
+                }),
+
+            helpHeading('settings', '#f59e0b', 'Settings on each question') +
+                helpPanel({
+                    bg: '#fffbeb',
+                    border: '#f59e0b',
+                    text: '#92400e',
+                    items: [
+                        '<strong>Label</strong> is the wording people read — write it as the question you want answered',
+                        '<strong>Required?</strong> set to Yes means the form cannot be submitted without an answer; required questions show an asterisk',
+                        '<strong>Size</strong> is how wide the question sits on the page: Full for its own row, Half or Quarter to share a row',
+                        '<strong>Height Size</strong> on a Textarea chooses a small, normal or large writing box',
+                        '<strong>Single or Bulk Image?</strong> decides whether one photo or several can be attached',
+                        '<strong>Associated Role?</strong> on a Signature says whose signature it is',
+                        'There is no help text, placeholder or preset answer — put any wording people need into the label, or a Plain Text block above',
+                    ],
+                }),
+
+            helpHeading('list', '#059669', 'Answers for Dropdown and Checkbox') +
+                helpPanel({
+                    bg: '#f0fdf4',
+                    border: '#059669',
+                    text: '#166534',
+                    items: [
+                        'Type the answer in the box at the bottom of the Options list and press Enter, or click <strong>+ Add</strong>',
+                        'Click straight into an existing answer to reword it; the bin removes it',
+                        'Two answers cannot share the same wording',
+                        'Rewording an answer can unhook rules that were pointing at it — check any "show only when" rule that used it',
+                    ],
+                }),
+
+            helpHeading('table', '#be185d', 'Grid questions') +
+                helpPanel({
+                    bg: '#fdf2f8',
+                    border: '#be185d',
+                    text: '#9d174d',
+                    items: [
+                        '<strong>Table (Radio)</strong> needs both Columns and Rows — the rows are the things being checked and the columns are the possible answers',
+                        '<strong>Table (Custom)</strong> needs Columns only, and gives one row of boxes to fill in',
+                        'Add a column or row by typing it in and pressing Enter, or clicking Add',
+                        'The rows are fixed when you build the template — the person filling in the form cannot add more',
+                    ],
+                }),
+
+            helpHeading(
+                'branch',
+                '#4f46e5',
+                'Showing a question only when it applies'
+            ) +
+                helpPanel({
+                    bg: '#eef2ff',
+                    border: '#4f46e5',
+                    text: '#3730a3',
+                    items: [
+                        'Every question window ends with <strong>Conditional Field Display Criteria</strong>',
+                        'Pick the earlier question it depends on, then either <strong>is</strong> with a value, or <strong>is filled in</strong>',
+                        'Only questions that come <em>before</em> this one can be used, and only ones that collect an answer',
+                        'A line at the bottom spells the rule out, e.g. "This field will only show when Advice type is Insurance"',
+                        'Leave it blank to always show the question, or use <strong>Clear rule</strong> to remove one',
+                        'Questions with a rule are marked "Conditional" in the list',
+                    ],
+                }),
+        ];
+
+        if (outstandingItems?.enabled) {
+            sections.push(
+                helpHeading('flag', '#d97706', 'Answers that raise a follow-up') +
+                    helpPanel({
+                        bg: '#fef3c7',
+                        border: '#d97706',
+                        text: '#92400e',
+                        items: [
+                            'On questions that offer answers, each answer has an <strong>Outstanding</strong> switch',
+                            'Turn it on for the answer that means "this needs following up", and the system raises an outstanding item when someone gives that answer',
+                            'Only one answer per question can be marked',
+                            'Leave every switch off to say this question never raises a follow-up',
+                            'If an amber warning appears, the answer the old rule pointed at no longer exists — set the switch again on the right answer',
+                        ],
+                    })
+            );
+        }
+
+        sections.push(
+            helpHeading('save', '#dc2626', 'Saving your work') +
+                helpPanel({
+                    bg: '#fef2f2',
+                    border: '#dc2626',
+                    text: '#991b1b',
+                    items: [
+                        '<strong>Apply</strong> inside a question window only adds it to the list on screen — nothing is stored yet',
+                        'To store the template, click <strong>Save Template</strong> (bottom right)',
+                        'The label beside those buttons reads <strong>Unsaved changes</strong> until you do, and the browser warns you if you try to leave',
+                        '<strong>Edit Form</strong> is only for renaming the template',
+                        'Moving a question saves the whole template straight away, so the order is never lost',
+                        'If someone else changed this template while you had it open, you are told nothing was saved — reload the page before saving again, or your changes would undo theirs',
+                    ],
+                })
+        );
+
+        Swal.fire({
+            title: `<div style="display: flex; align-items: center; justify-content: center; gap: 8px;">${helpIcon(
+                'help',
+                '#3b82f6'
+            )}Form Builder Guide</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',
+            customClass: {
+                popup: 'comprehensive-help-modal',
+                htmlContainer: 'help-content-scrollable',
+            },
+        });
+    };
+
+    // Show the guide once, the first time someone opens the builder.
+    useEffect(() => {
+        if (localStorage.getItem('formBuilder_hasSeenHelp')) return;
+
+        const timer = setTimeout(() => {
+            showGuidedHelp();
+            localStorage.setItem('formBuilder_hasSeenHelp', 'true');
+        }, 500);
+
+        return () => clearTimeout(timer);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
     return (
         <div className={modalShow || modalFormShow ? styles.modalOpen : ''}>
             <div className={styles.grid}>
@@ -2081,6 +2470,15 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                         ).length}{' '}
                                         sections
                                     </span>
+                                    <button
+                                        type="button"
+                                        className={styles.toolBtn}
+                                        onClick={showGuidedHelp}
+                                        data-tooltip-id="action-tooltip"
+                                        data-tooltip-content="How to build this form"
+                                    >
+                                        <HelpCircle size={15} /> Help
+                                    </button>
                                     <button
                                         className={`${styles.toolBtn} ${
                                             showOutline ? styles.toolBtnOn : ''
@@ -2307,6 +2705,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                             )}
                         </div>
                         <div className={styles.polActions}>
+                            {/* The only honest answer to "have my changes been
+                                stored?". Everything else on this screen edits a
+                                copy held in the browser. */}
+                            <span
+                                className={`${styles.saveState} ${
+                                    unsavedChanges
+                                        ? styles.saveStateDirty
+                                        : styles.saveStateClean
+                                }`}
+                            >
+                                {unsavedChanges
+                                    ? 'Unsaved changes'
+                                    : 'All changes saved'}
+                            </span>
                             {/* Nothing to author on a dynamic template, but
                                 Edit Form stays so it can still be renamed. */}
                             {!dynamicFields && (
@@ -2323,6 +2735,19 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                             >
                                 Edit Form
                             </button>
+                            {/* Was reachable only through Edit Form — a window
+                                titled "Update Form Detail" showing nothing but
+                                the label, so the action that stores the
+                                questions looked like the one that renames the
+                                form. It belongs out here, beside the work. */}
+                            <button
+                                className={`${styles.btn} ${styles.btnPrimary}`}
+                                onClick={handleSubmit}
+                                data-tooltip-id="system-tooltip"
+                                data-tooltip-content="Store this template. Question windows only stage changes on screen."
+                            >
+                                Save Template
+                            </button>
                         </div>
                     </div>
                 </div>
@@ -3140,11 +3565,23 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                     <div
                                         className={`${styles.formItem} ${styles.fwItem} ${styles.lastItem}`}
                                     >
+                                        {/* This window has never stored
+                                            anything — it edits the copy held in
+                                            the browser. Calling its button
+                                            "Save" was the whole reason people
+                                            left the screen believing their work
+                                            had been filed. */}
+                                        <p className={styles.applyHint}>
+                                            Adds this question to the list on
+                                            screen. Use{' '}
+                                            <strong>Save Template</strong> to
+                                            store it.
+                                        </p>
                                         <button
                                             className={`${styles.btn}`}
                                             onClick={handleSaveField}
                                         >
-                                            Save
+                                            Apply
                                         </button>
                                     </div>
                                 </form>

package/src/components/generic/GenericReport.jsx

@@ -1752,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',
@@ -1980,7 +1812,324 @@ 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(() => {
@@ -1994,12 +2143,17 @@ const GenericReportImproved = ({
 
         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, semanticStatus]); // Re-fetch when URLs change

package/src/components/styles/GenericFormBuilder.module.scss

@@ -643,7 +643,8 @@ select:not(:placeholder-shown) + .fi__span {
     overflow: visible;
     position: relative;
     z-index: 100;
-    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.15),
+    box-shadow:
+        0 20px 60px rgba(0, 0, 0, 0.15),
         0 0 0 1px rgba(var(--primary-rgb), 0.06);
 }
 
@@ -786,9 +787,6 @@ select:not(:placeholder-shown) + .fi__span {
 
 /* Adding btn class */
 
-
-
-
 /* Floating action buttons */
 .polActions {
     position: fixed;
@@ -801,9 +799,11 @@ select:not(:placeholder-shown) + .fi__span {
     background: rgba(255, 255, 255, 0.95);
     padding: 10px 14px;
     border-radius: 12px;
-    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12),
+    box-shadow:
+        0 4px 20px rgba(0, 0, 0, 0.12),
         0 0 0 1px rgba(var(--primary-rgb), 0.08);
     backdrop-filter: blur(8px);
+    align-items: center;
 
     button {
         display: block;
@@ -814,6 +814,50 @@ select:not(:placeholder-shown) + .fi__span {
     }
 }
 
+/* Stored or not — the one thing this screen never used to say out loud. */
+.saveState {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0 6px;
+    font-size: 0.8rem;
+    font-weight: 600;
+    white-space: nowrap;
+
+    &::before {
+        content: '';
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: currentColor;
+    }
+}
+
+.saveStateDirty {
+    color: #b45309;
+}
+
+.saveStateClean {
+    color: #15803d;
+}
+
+/* The save that actually writes, weighted so it reads as the end of the job. */
+.btnPrimary {
+    box-shadow: 0 0 0 2px rgba(var(--primary-rgb), 0.35);
+}
+
+/* Sits under the question window's Apply, where the misunderstanding happens. */
+.applyHint {
+    flex: 1;
+    align-self: center;
+    margin: 0;
+    padding-right: 1rem;
+    font-size: 0.78rem;
+    line-height: 1.35;
+    color: var(--text-color-light, #6b7280);
+    text-align: left;
+}
+
 .fwItem {
     flex-basis: 100%;
 }
@@ -1337,6 +1381,12 @@ select:not(:placeholder-shown) + .fi__span {
 .dragHandle {
     color: var(--primary-color) !important;
     cursor: grab;
+    /* Same reason as .cGrip: on iPadOS the browser treats a press-and-move on
+       this handle as a scroll unless the element opts out, so the drag never
+       activates and reordering is silently unavailable. */
+    touch-action: none;
+    -webkit-user-select: none;
+    user-select: none;
     padding: 4px;
     border-radius: 6px;
     background: white;
@@ -2047,7 +2097,8 @@ select:not(:placeholder-shown) + .fi__span {
     border-radius: 12px;
     padding: 1.25rem 1.5rem;
     width: 280px;
-    box-shadow: 0 16px 48px rgba(0, 0, 0, 0.18),
+    box-shadow:
+        0 16px 48px rgba(0, 0, 0, 0.18),
         0 0 0 1px rgba(var(--primary-rgb), 0.08);
 
     h3 {
@@ -2472,7 +2523,6 @@ select:not(:placeholder-shown) + .fi__span {
     margin-right: -1.15rem !important;
 }
 
-
 /* The header and search span both columns; only the rail and canvas sit
    side by side. */
 
@@ -2622,9 +2672,6 @@ select:not(:placeholder-shown) + .fi__span {
 
 /* ---- compact rows ---- */
 
-
-
-
 .duplicateBtn {
     display: flex;
     align-items: center;
@@ -2705,6 +2752,12 @@ select:not(:placeholder-shown) + .fi__span {
     align-items: center;
     color: rgba(var(--paragraph-rgb), 0.4);
     cursor: grab;
+    /* dnd-kit's PointerSensor cannot start a drag from an element the browser
+       has already claimed for scrolling. Without this the grip does nothing at
+       all on a touch screen — the page just scrolls under the finger. */
+    touch-action: none;
+    -webkit-user-select: none;
+    user-select: none;
 
     &:active {
         cursor: grabbing;