@visns-studio/visns-components 6.1.8 → 6.2.0

package/README.md

@@ -3300,13 +3300,173 @@ A powerful and enhanced report building component that provides an intuitive wiz
         columnUrl: '/ajax/reportBuilder/getTableColumns',
         reportsUrl: '/ajax/reportBuilder/reports',
         executeUrl: '/ajax/reportBuilder/execute',
-        suggestedJoinsUrl: '/ajax/reportBuilder/getSuggestedJoins',
+        detectedJoinsUrl: '/ajax/reportBuilder/getSuggestedJoins',
+        exportUrl: '/ajax/reportBuilder/export',
+        semanticModelUrl: '/ajax/reportBuilder/semanticModel',
     }}
     userProfile={userProfile}
     businessTemplates={businessTemplates} // Optional pre-built templates
 />
 ```
 
+**Semantic Mode (report definition v2)**
+
+On mount the component POSTs to `setting.semanticModelUrl` (default
+`/ajax/reportBuilder/semanticModel`). If it responds with
+`{success: true, data: {entities: {...}}}` the wizard switches to **semantic
+mode**, where the user picks business entities, labelled fields and labelled
+relations — no table or column names are ever shown. If the endpoint 404s or
+errors, the wizard silently falls back to **legacy mode** (the existing
+table/column/join behaviour), so this is fully backwards compatible.
+
+Semantic model response shape:
+
+```json
+{
+    "success": true,
+    "data": {
+        "entities": {
+            "clients": {
+                "label": "Clients",
+                "plural": "Clients",
+                "description": "People the practice advises",
+                "fields": {
+                    "firstname": { "label": "First name", "type": "text" },
+                    "fee_amount": {
+                        "label": "Fee amount",
+                        "type": "money",
+                        "summable": true
+                    },
+                    "fds_due_date": { "label": "FDS due date", "type": "date" },
+                    "status": {
+                        "label": "Status",
+                        "type": "enum",
+                        "values": { "1": "Active", "0": "Inactive" }
+                    }
+                },
+                "relations": {
+                    "adviser": {
+                        "label": "Their adviser",
+                        "entity": "users",
+                        "cardinality": "one"
+                    },
+                    "notes": {
+                        "label": "Their notes",
+                        "entity": "client_notes",
+                        "cardinality": "many"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Field types are `text | number | money | percent | date | datetime | boolean | enum`.
+Field ids are opaque handles — the server maps them to storage, so the client
+never needs to know the underlying table or column.
+
+The wizard builds a **report definition v2** document, saves it in `detail`, and
+POSTs it when running or exporting the report:
+
+```json
+{
+    "schema_version": 2,
+    "entity": "clients",
+    "fields": [
+        { "field": "firstname" },
+        { "field": "adviser.name" },
+        { "agg": "sum", "field": "fee_amount", "label": "Total fees" }
+    ],
+    "filters": {
+        "op": "and",
+        "items": [
+            { "field": "status", "operator": "equals", "value": "1" },
+            {
+                "op": "or",
+                "items": [
+                    { "field": "home_email", "operator": "not_empty" },
+                    { "field": "work_email", "operator": "not_empty" }
+                ]
+            },
+            {
+                "field": "fds_due_date",
+                "operator": "between",
+                "param": "due_range"
+            }
+        ]
+    },
+    "parameters": [
+        {
+            "id": "due_range",
+            "label": "Due date range",
+            "type": "date_range",
+            "required": true
+        }
+    ],
+    "groupBy": ["adviser.name"],
+    "sort": [{ "field": "surname", "dir": "asc" }]
+}
+```
+
+-   **Relation dot-paths**: a `relation.field` path (e.g. `adviser.name`) reaches
+    a field through a declared relation. Only relations declared in the semantic
+    model can be traversed.
+-   **Aggregates**: `sum | count | avg | min | max`. `sum` and `avg` are offered
+    only on fields marked `summable: true` or typed `number`, `money` or
+    `percent`; `count` is available on anything.
+-   **Runtime parameters**: a filter carrying `param` instead of `value` is a
+    runtime parameter — the run screen prompts for it using the matching entry
+    in `parameters` before executing.
+
+**Operators by field type:**
+
+| Field type              | Operators                                                                   |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `text`                  | `equals`, `not_equals`, `contains`, `not_contains`, `is_empty`, `not_empty`  |
+| `number`/`money`/`percent` | `equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`, `is_empty`, `not_empty` |
+| `date`/`datetime`       | `equals`, `before`, `after`, `between`, `is_empty`, `not_empty`              |
+| `boolean`               | `is_true`, `is_false`                                                        |
+| `enum`                  | `equals`, `not_equals`, `in`, `not_in`                                       |
+
+**Execute contract:**
+
+-   `POST executeUrl` with `{definition, parameters, limit, offset}` →
+    `{success, data: [rows], total}`. Each row is keyed by the field path or the
+    aggregate label exactly as given in `fields` — e.g. `"firstname"`,
+    `"adviser.name"`, `"Total fees"`.
+-   `POST exportUrl` with `{definition, parameters, format}` → a file blob.
+
+Save/load endpoints are unchanged; `detail` simply holds the v2 document. A
+legacy v1 document (one that has `mainTable`) keeps the current legacy
+behaviour.
+
+The pure helpers behind all of this live in
+`src/components/generic/reportSemantics.js` (model lookup, operator menus,
+definition serialisation) with the endpoint probe in
+`src/components/generic/useSemanticModel.js`. They are covered by:
+
+```bash
+node --test tests/reportSemantics.test.mjs
+```
+
+**Embeddable grouped report viewers**
+
+`GroupedReportRenderer` and `SectionGroupedReport` are exported so consuming apps
+can embed a read-only grouped report view without the wizard. Columns accept an
+explicit `key` (the exact row key returned by the execute contract) and a
+`header` label:
+
+```jsx
+import { GroupedReportRenderer } from '@visns-studio/visns-components';
+
+<GroupedReportRenderer
+    data={{ grouped: true, groups, totalGroups, totalRecords }}
+    config={{ type: 'sections', groupDisplayName: 'Adviser' }}
+    columns={[{ key: 'adviser.name', header: 'Adviser' }]}
+/>;
+```
+
 **Major Enhancements:**
 
 -   **6-Step Wizard Interface**: Guided workflow with visual progress indicators

package/package.json

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

package/src/components/Fetch.jsx

@@ -124,6 +124,41 @@ const invalidateRelatedCaches = (url, method) => {
     }
 };
 
+/**
+ * Turn an API error bag into displayable HTML, whatever shape it arrived in.
+ *
+ * Laravel validation sends `{field: ["msg", ...]}`; the report-semantics
+ * endpoints send `[{path, message}, ...]` (see report-semantics.md §6). A bare
+ * list of strings is accepted too. Anything unreadable yields '' so the caller
+ * can fall back to `data.message` — never a thrown TypeError, which used to
+ * leave the request promise permanently unsettled.
+ */
+const flattenErrorBag = (errors) => {
+    const lines = [];
+
+    const collect = (entry) => {
+        if (entry === null || entry === undefined) return;
+        if (Array.isArray(entry)) {
+            entry.forEach(collect);
+            return;
+        }
+        if (typeof entry === 'object') {
+            // `{path, message}` from the semantic compiler.
+            if (typeof entry.message === 'string') {
+                lines.push(entry.message);
+                return;
+            }
+            Object.values(entry).forEach(collect);
+            return;
+        }
+        lines.push(String(entry));
+    };
+
+    collect(errors);
+
+    return lines.filter(Boolean).map((line) => `${line}<br />`).join('');
+};
+
 // Original CustomFetch logic extracted for reuse
 const originalCustomFetch = (
     url,
@@ -275,13 +310,12 @@ const originalCustomFetch = (
                     const { data } = error.response;
 
                     if (data.errors) {
-                        const { errors } = data;
-
-                        Object.values(errors).forEach((errorArray) => {
-                            errorArray.forEach((errorMsg) => {
-                                errorMessage += `${errorMsg}<br />`;
-                            });
-                        });
+                        errorMessage = flattenErrorBag(data.errors);
+                        // A bag we could not read (or an empty one) must still
+                        // surface something the user can act on.
+                        if (!errorMessage && data.message) {
+                            errorMessage = data.message;
+                        }
                     } else if (data.message) {
                         if (data.message === 'CSRF token mismatch.') {
                             window.location.replace('/login');
@@ -345,12 +379,10 @@ const CustomFetch = (
                     if (error.response && error.response.data) {
                         const { data } = error.response;
                         if (data.errors) {
-                            const { errors } = data;
-                            Object.values(errors).forEach((errorArray) => {
-                                errorArray.forEach((errorMsg) => {
-                                    errorMessage += `${errorMsg}<br />`;
-                                });
-                            });
+                            errorMessage =
+                                flattenErrorBag(data.errors) ||
+                                data.message ||
+                                '';
                         } else if (data.message) {
                             errorMessage = data.message;
                         }
@@ -364,12 +396,10 @@ const CustomFetch = (
                     if (error.response && error.response.data) {
                         const { data } = error.response;
                         if (data.errors) {
-                            const { errors } = data;
-                            Object.values(errors).forEach((errorArray) => {
-                                errorArray.forEach((errorMsg) => {
-                                    errorMessage += `${errorMsg}<br />`;
-                                });
-                            });
+                            errorMessage =
+                                flattenErrorBag(data.errors) ||
+                                data.message ||
+                                '';
                         } else if (data.message) {
                             if (data.message === 'CSRF token mismatch.') {
                                 window.location.replace('/login');