ui-soxo-bootstrap-core 2.6.0 → 2.6.1-dev.10

package/core/modules/reporting/components/reporting-dashboard/README.md

@@ -0,0 +1,316 @@
+# Reporting Dashboard
+
+This module renders configurable reports using:
+- backend-driven `input_parameters` (filter form)
+- backend-driven `display_columns` (table columns)
+- report data from `CoreScripts.getReportingLisitng(...)`
+
+Main component:
+- `core/modules/reporting/components/reporting-dashboard/reporting-dashboard.js`
+
+Display column internals:
+- `core/modules/reporting/components/reporting-dashboard/display-columns/build-display-columns.js`
+- `core/modules/reporting/components/reporting-dashboard/display-columns/display-cell-renderer.js`
+
+## Data Flow Overview
+
+1. Dashboard loads `CoreScripts.getRecord({ id, dbPtr })`.
+2. It parses:
+- `input_parameters` JSON string -> filter form configuration
+- `display_columns` JSON string -> table column configuration
+3. It submits filter values to `CoreScripts.getReportingLisitng(coreScriptId, formBody, dbPtr)`.
+4. It renders the table with configured display columns.
+
+If `display_columns` is missing, columns are auto-generated from response keys.
+
+## ReportingDashboard Props
+
+Common props:
+- `match` / `reportId`: report id source (`reportId` overrides route id)
+- `dbPtr`: db pointer (falls back to `localStorage.db_ptr`)
+- `CustomComponents`: map of reusable custom components
+- `scope`: optional object to override filter payload body
+- `dashBoardIds`: optional cards for dashboard switching
+- `showScanner`: enables QR scanner button
+- `barcodeFilterKey`: field used to match scanned QR value
+- `isFixedIndex`: fixes index `#` column to left
+- `attributes`: JSON string for extra UI controls (for example `buttonAttributes`)
+
+## Input Parameters Configuration
+
+`input_parameters` is stored as a JSON string in backend and parsed at runtime.
+
+Example:
+
+```json
+[
+  {
+    "title": "From Date",
+    "field": "start",
+    "type": "date",
+    "default": "startOfDay",
+    "required": true
+  },
+  {
+    "title": "To Date",
+    "field": "end",
+    "type": "date",
+    "default": "endOfDay",
+    "required": true
+  },
+  {
+    "title": "Department",
+    "field": "dept_id",
+    "type": "reference-select",
+    "modelName": "Department",
+    "required": false
+  },
+  {
+    "title": "Status",
+    "field": "status",
+    "type": "select",
+    "options": [
+      { "label": "Pending", "value": "Pending" },
+      { "label": "Completed", "value": "Completed" }
+    ]
+  }
+]
+```
+
+### Supported default date values
+
+For `type: "date"`, supported `default` values:
+- `startOfDay`
+- `endOfDay`
+- `startOfWeek`
+- `endOfWeek`
+- `currentDate`
+
+If no date default is provided, current date is used.
+
+### URL synchronization
+
+- On load, if URL contains `?field=value`, that value is used over defaults.
+- On submit, active input values are written back to URL query params.
+- Date values are URL-formatted as `YYYY-MM-DD`.
+
+### Hiding input parameter form
+
+If `other_details1` JSON includes:
+
+```json
+{ "isDisableInputParameters": true }
+```
+
+the input form is hidden, but report data still loads.
+
+## Display Columns Configuration
+
+`display_columns` is also a backend JSON string.
+
+Each entry maps to one table column.
+
+Basic example:
+
+```json
+[
+  { "title": "OP No", "field": "opno", "isSortingEnabled": true },
+  { "title": "Guest Name", "field": "guest_name", "isFilterEnabled": true },
+  { "title": "Amount", "field": "amount", "type": "number", "width": 120 }
+]
+```
+
+### Common column keys
+
+- `title`: header text
+- `tooltip`: optional header tooltip override
+- `field`: record key to display
+- `width`: numeric width (default `160`)
+- `isFixedColumn`: AntD fixed position (`"left"` / `"right"`)
+- `isFilterEnabled`: generates unique-value filters from table data
+- `isSortingEnabled`: enables string sort on `field`
+- `color`: default text color
+- `type: "number"`: right-aligns cell
+
+## Action Columns (Backward-Compatible Rules)
+
+Action logic is intentionally layered to avoid breaking existing reports.
+
+Compatibility rules:
+1. `entry.field === "action"` -> **legacy action** behavior
+2. else if `entry.type === "action"` -> **new action layer**
+3. all other types use existing non-action behavior
+
+### Legacy action example (existing reports)
+
+```json
+{
+  "title": "Action",
+  "field": "action",
+  "redirect_link": "/process/@opb_id;",
+  "replace_variables": [{ "field": "opb_id" }],
+  "display_name_link": "View"
+}
+```
+
+Legacy label behavior:
+- `display_name_link` or `"View"`
+
+### New action layer example (dynamic API label)
+
+```json
+{
+  "title": "Action",
+  "type": "action",
+  "field": "action_text",
+  "redirect_link": "/process/@opb_id;",
+  "replace_variables": [{ "field": "opb_id" }],
+  "label": "View"
+}
+```
+
+New action label fallback order:
+1. `record[entry.field]` (example: `record.action_text`)
+2. `entry.label`
+3. `entry.display_name_link`
+4. `"View"`
+
+## Other Display Types
+
+### External link column
+
+```json
+{ "title": "Report", "field": "report_url", "type": "link" }
+```
+
+Renders anchor with `View` label if URL exists.
+
+### Color tag or span
+
+```json
+{ "title": "Status", "field": "status", "enableColor": true, "columnType": "tag" }
+```
+
+or
+
+```json
+{ "title": "Status", "field": "status", "enableColor": true, "columnType": "span" }
+```
+
+Uses `record.color_code`.
+
+### Dynamic icon mapping
+
+```json
+{
+  "title": "State",
+  "field": "state",
+  "displayIcons": {
+    "Pending": { "icon": "ClockCircleOutlined", "color": "orange", "size": "14px" },
+    "Done": { "icon": "CheckCircleOutlined", "color": "green", "size": "14px" }
+  }
+}
+```
+
+Icon names are taken from `@ant-design/icons`.
+
+### Custom component column
+
+```json
+{
+  "title": "Info",
+  "field": "custom",
+  "component": "ResultEntryInfo",
+  "props": [
+    { "field": "description_text", "value": "description" },
+    { "field": "opb_id", "value": "opbId" }
+  ],
+  "config": { "allowEdit": true }
+}
+```
+
+How it resolves:
+- `component` must exist in merged `CustomComponents`
+- each `props` item maps `record[field]` to prop key `value`
+- `config` is spread as static props
+- `callback` prop triggers dashboard `refresh()`
+
+## Redirect Template Variables
+
+Action redirects support template replacement in `redirect_link`:
+- placeholder format: `@field;`
+- replacements defined in `replace_variables`
+
+Example:
+
+```json
+{
+  "redirect_link": "/lab/@opb_id;/visit/@opno;",
+  "replace_variables": [{ "field": "opb_id" }, { "field": "opno" }]
+}
+```
+
+With row `{ "opb_id": 12, "opno": "OP-55" }`:
+- result -> `/lab/12/visit/OP-55`
+
+## QR Scanner Behavior
+
+When scanner is enabled:
+- scanned value is matched against `patient[barcodeFilterKey]`
+- redirect uses first configured action column with this priority:
+1. legacy action column (`field === "action"`)
+2. new action column (`type === "action"`)
+
+## Export Behavior
+
+- Export uses current table columns.
+- For `field === "custom"`, export attempts to read the prop mapping where `value === "description"` and exports that source field.
+- Other columns export `record[field]`.
+
+## End-to-End Example
+
+`display_columns`:
+
+```json
+[
+  { "title": "OP No", "field": "opno", "isSortingEnabled": true, "width": 140 },
+  { "title": "Guest", "field": "guest_name", "isFilterEnabled": true, "width": 220 },
+  {
+    "title": "Status",
+    "field": "status",
+    "enableColor": true,
+    "columnType": "tag"
+  },
+  {
+    "title": "Action",
+    "type": "action",
+    "field": "action_text",
+    "redirect_link": "/process-detail/@opb_id;",
+    "replace_variables": [{ "field": "opb_id" }],
+    "label": "View"
+  }
+]
+```
+
+Sample API row:
+
+```json
+{
+  "opb_id": 1001,
+  "opno": "OP-1001",
+  "guest_name": "Aisha Rahman",
+  "status": "Pending",
+  "color_code": "orange",
+  "action_text": "Start Consultation"
+}
+```
+
+Rendered action label:
+- `Start Consultation` (dynamic value from API)
+
+## Notes for Developers
+
+- Keep `display_columns` as JSON string in DB for backward compatibility.
+- Prefer `type: "action"` for new dynamic action labels.
+- Reserve `field: "action"` for legacy behavior.
+- If adding new display types, implement in `display-cell-renderer.js` and keep order explicit.

package/core/modules/reporting/components/reporting-dashboard/adavance-search/advance-search.js

@@ -0,0 +1,120 @@
+
+
+import React, { useState, useEffect, useRef } from "react";
+import { Select, Checkbox, Input, Spin } from "antd";
+import { CoreScripts } from "../../../../../models";
+
+const { Search } = Input;
+
+export default function AdvancedSearchSelect({ field, value = [], onChange }) {
+  const [searchResults, setSearchResults] = useState([]); // only API results
+  const [selectedItems, setSelectedItems] = useState(value); // persisted selections
+  const [loading, setLoading] = useState(false);
+  const debounceRef = useRef(null);
+
+  // Sync selectedItems if parent value changes externally
+  useEffect(() => {
+    setSelectedItems(value);
+  }, [value]);
+
+  const loadOptions = async (searchText = "") => {
+    try {
+      setLoading(true);
+
+      let query = field?.search_query || "";
+      query = query.replace("@search_text;", searchText || "");
+
+      const res = await CoreScripts.getQuery({ script: query });
+      const data = Array.isArray(res) ? res[0] : [];
+      const apiValues = data?.map((r) => r[field.field]) || [];
+
+      setSearchResults(apiValues);
+    } catch (error) {
+      console.error("Search API error", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    loadOptions("");
+  }, [field]);
+
+  const handleSearch = (text) => {
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => loadOptions(text), 400);
+  };
+
+  const toggleValue = (checked, item) => {
+    let newValues;
+
+    if (checked) {
+      newValues = [...selectedItems, item];
+    } else {
+      newValues = selectedItems.filter((v) => v !== item);
+    }
+
+    setSelectedItems(newValues); // update local persisted state immediately
+    onChange(newValues);
+  };
+
+  // Merge: selected items always on top, then search results (excluding already selected)
+  const displayOptions = [
+    ...selectedItems,
+    ...searchResults.filter((item) => !selectedItems.includes(item)),
+  ];
+
+  return (
+    <Select
+      mode="multiple"
+      value={value}
+      style={{ width: 250 }}
+      placeholder={field.caption}
+      allowClear
+      maxTagCount={0}
+      onChange={onChange}
+      maxTagPlaceholder={() => (
+        <span style={{ display: "flex", alignItems: "center", gap: 8 }}>
+          {field.caption}
+          <span
+            style={{
+              background: "#e6f0ff",
+              color: "#1677ff",
+              borderRadius: "10px",
+              padding: "0 8px",
+              fontWeight: 600,
+              fontSize: 12,
+            }}
+          >
+            {value?.length || 0}
+          </span>
+        </span>
+      )}
+      dropdownRender={() => (
+        <div style={{ padding: 10 }}>
+          <Search
+            placeholder={`Search ${field.caption}`}
+            onChange={(e) => handleSearch(e.target.value)}
+          />
+
+          <div style={{ maxHeight: 200, overflowY: "auto", marginTop: 10 }}>
+            {loading ? (
+              <Spin />
+            ) : (
+              displayOptions.map((item) => (
+                <div key={item} style={{ marginBottom: 6 }}>
+                  <Checkbox
+                    checked={selectedItems.includes(item)}
+                    onChange={(e) => toggleValue(e.target.checked, item)}
+                  >
+                    {item}
+                  </Checkbox>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+      )}
+    />
+  );
+}

package/core/modules/reporting/components/reporting-dashboard/display-columns/build-display-columns.js

@@ -0,0 +1,75 @@
+import React from 'react';
+import { Tooltip } from 'antd';
+import { renderDisplayCell } from './display-cell-renderer';
+
+/**
+ * Resolves export value definition for a configured display column.
+ *
+ * @param {Object} entry
+ * @param {Object} record
+ * @returns {*}
+ */
+function getExportDefinition(entry, record) {
+  if (entry.field === 'custom') {
+    const description = entry.props?.find((p) => p.value === 'description')?.field;
+    return description && record[description] ? record[description] : null;
+  }
+
+  return record[entry.field];
+}
+
+/**
+ * Builds Ant Design table columns from display column configuration.
+ *
+ * @param {Object} root0
+ * @param {Array} root0.columns
+ * @param {Array} root0.patients
+ * @param {boolean} root0.isFixedIndex
+ * @param {Object} root0.CustomComponents
+ * @param {Function} root0.refresh
+ * @returns {Array}
+ */
+export default function buildDisplayColumns({ columns = [], patients = [], isFixedIndex, CustomComponents, refresh }) {
+  const displayColumns = [
+    {
+      title: '#',
+      dataIndex: 'index',
+      render: (value, item, index) => index + 1,
+      key: 'ColumnIndex',
+      fixed: isFixedIndex ? 'left' : null,
+      width: 2,
+    },
+  ];
+
+  columns.forEach((entry, index) => {
+    displayColumns.push({
+      render: (record) =>
+        renderDisplayCell({
+          entry,
+          record,
+          CustomComponents,
+          refresh,
+        }),
+      field: entry.field,
+      title: (
+        <Tooltip title={entry.tooltip || entry.title}>
+          <span>{entry.title}</span>
+        </Tooltip>
+      ),
+      key: entry.field || `display_column_${index}`,
+      width: entry.width ? parseInt(entry.width, 10) : 160,
+      fixed: entry.isFixedColumn ? entry.isFixedColumn : null,
+      filters:
+        entry.isFilterEnabled && Array.isArray(patients)
+          ? [...new Set(patients.map((item) => item[entry.field]).filter(Boolean))].map((value) => ({ text: value, value }))
+          : null,
+      onFilter: entry.isFilterEnabled ? (value, record) => record[entry.field] === value : null,
+      sorter: entry.isSortingEnabled ? (a, b) => String(a[entry.field]).localeCompare(String(b[entry.field])) : null,
+      filterSearch: entry.isFilterEnabled ? entry.isFilterEnabled : false,
+      exportDefinition: (record) => getExportDefinition(entry, record),
+      align: entry.type === 'number' ? 'right' : 'left',
+    });
+  });
+
+  return displayColumns;
+}

package/core/modules/reporting/components/reporting-dashboard/display-columns/build-display-columns.test.js

@@ -0,0 +1,74 @@
+import React from 'react';
+import buildDisplayColumns from './build-display-columns';
+
+describe('build-display-columns', () => {
+  test('creates index column plus configured columns', () => {
+    const columns = buildDisplayColumns({
+      columns: [{ title: 'OP NO', field: 'opno' }],
+      patients: [{ opno: 'OP-1' }],
+      isFixedIndex: true,
+      CustomComponents: {},
+      refresh: jest.fn(),
+    });
+
+    expect(columns.length).toBe(2);
+    expect(columns[0].key).toBe('ColumnIndex');
+    expect(columns[0].fixed).toBe('left');
+    expect(columns[1].field).toBe('opno');
+  });
+
+  test('preserves legacy action behavior and supports new action dynamic label', () => {
+    const refresh = jest.fn();
+    const columns = buildDisplayColumns({
+      columns: [
+        {
+          title: 'Legacy Action',
+          field: 'action',
+          redirect_link: '/legacy/@opb_id;',
+          replace_variables: [{ field: 'opb_id' }],
+          display_name_link: 'Open',
+        },
+        {
+          title: 'New Action',
+          type: 'action',
+          field: 'action_text',
+          redirect_link: '/new/@opb_id;',
+          replace_variables: [{ field: 'opb_id' }],
+          label: 'Fallback',
+        },
+      ],
+      patients: [{ opb_id: 10, action: 'Should not replace legacy label', action_text: 'Review' }],
+      isFixedIndex: false,
+      CustomComponents: {},
+      refresh,
+    });
+
+    const row = { opb_id: 10, action: 'Should not replace legacy label', action_text: 'Review' };
+
+    const legacyElement = columns[1].render(row);
+    const newLayerElement = columns[2].render(row);
+
+    expect(legacyElement.props.children).toBe('Open');
+    expect(newLayerElement.props.children).toBe('Review');
+  });
+
+  test('custom exportDefinition returns mapped description field value', () => {
+    const columns = buildDisplayColumns({
+      columns: [
+        {
+          title: 'Info',
+          field: 'custom',
+          props: [{ field: 'status_text', value: 'description' }],
+        },
+      ],
+      patients: [],
+      isFixedIndex: false,
+      CustomComponents: {},
+      refresh: jest.fn(),
+    });
+
+    const exportValue = columns[1].exportDefinition({ status_text: 'Ready' });
+    expect(exportValue).toBe('Ready');
+  });
+});
+