@cccsaurora/howler-ui 2.19.0-dev.1260 → 2.19.0-dev.1266

package/components/elements/display/HandlebarsMarkdown.js

@@ -7,7 +7,17 @@ import { useTranslation } from 'react-i18next';
 import Throttler from '@cccsaurora/howler-ui/utils/Throttler';
 import { hashCode } from '@cccsaurora/howler-ui/utils/utils';
 import Markdown, {} from '../display/Markdown';
-import { useHelpers } from './handlebars/helpers';
+import { HowlerHelperError, useHelpers } from './handlebars/helpers';
+class HowlerHandlebarsRenderError extends Error {
+    helper;
+    hint;
+    constructor(message, helper, hint) {
+        super(Handlebars.escapeExpression(message));
+        this.name = 'HowlerHandlebarsRenderError';
+        this.helper = Handlebars.escapeExpression(helper);
+        this.hint = hint ? Handlebars.escapeExpression(hint) : undefined;
+    }
+}
 const THROTTLER = new Throttler(500);
 const HandlebarsMarkdown = ({ md, object = {}, disableLinks = false }) => {
     const { t } = useTranslation();
@@ -48,7 +58,23 @@ const HandlebarsMarkdown = ({ md, object = {}, disableLinks = false }) => {
                     }
                     return new Handlebars.SafeString(`\`${id}\``);
                 }
-                return helper.callback(...args);
+                try {
+                    const result = helper.callback(...args);
+                    return result instanceof Promise
+                        ? result.catch(err => {
+                            if (err instanceof HowlerHelperError) {
+                                throw new HowlerHandlebarsRenderError(err.message, helper.keyword, helper.hint);
+                            }
+                            throw err;
+                        })
+                        : result;
+                }
+                catch (err) {
+                    if (err instanceof HowlerHelperError) {
+                        throw new HowlerHandlebarsRenderError(err.message, helper.keyword, helper.hint);
+                    }
+                    throw err;
+                }
             });
         });
     }, [handlebars, helpers, mdComponents]);
@@ -65,6 +91,14 @@ const HandlebarsMarkdown = ({ md, object = {}, disableLinks = false }) => {
                     setRendered(await compiled(object));
                     return;
                 }
+                if (err instanceof HowlerHandlebarsRenderError) {
+                    setRendered(`
+<h2 style="color: red">${t('markdown.error')}</h2>
+<span style="color: red; font-weight: bold; font-family: monospace;">Invalid Usage [${err.helper}]: ${err.message}</span>
+${err.hint ? `<br/><span style="color: gray; font-family: monospace;">${err.hint}</span>` : ''}
+          `);
+                    return;
+                }
                 // eslint-disable-next-line no-console
                 console.error(err);
                 setRendered(`

package/components/elements/display/handlebars/helpers.d.ts

@@ -7,9 +7,13 @@ export interface HowlerHelper {
         fr: string;
     };
     async?: boolean;
+    hint?: string;
     callback?: Handlebars.HelperDelegate;
     componentCallback?: (...args: any[]) => ReactElement | Promise<ReactElement>;
 }
+export declare class HowlerHelperError extends Error {
+    constructor(message: string);
+}
 export declare const useHelpers: (opts?: {
     async: boolean;
     components: boolean;

package/components/elements/display/handlebars/helpers.js

@@ -6,12 +6,18 @@ import HitCard from '@cccsaurora/howler-ui/components/elements/hit/HitCard';
 import { HitLayout } from '@cccsaurora/howler-ui/components/elements/hit/HitLayout';
 import { flatten } from 'flat';
 import Handlebars from 'handlebars';
-import { capitalize, get, groupBy, isObject } from 'lodash-es';
+import { capitalize, get, groupBy, isNil, isObject } from 'lodash-es';
 import howlerPluginStore from '@cccsaurora/howler-ui/plugins/store';
 import { useMemo } from 'react';
 import { usePluginStore } from 'react-pluggable';
 import ActionButton from '../ActionButton';
 import JSONViewer from '../json/JSONViewer';
+export class HowlerHelperError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HowlerHelperError';
+    }
+}
 const FETCH_RESULTS = {};
 export const useHelpers = (opts = { async: true, components: true }) => {
     const pluginStore = usePluginStore();
@@ -22,7 +28,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Checks the equality of the string representation of the two arguments.',
                 fr: "Vérifie l'égalité de la représentation en chaîne de caractères des deux arguments."
             },
-            callback: (arg1, arg2) => arg1?.toString() === arg2.toString()
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [arg1, arg2] = args;
+                if (isNil(arg1) || isNil(arg2)) {
+                    throw new HowlerHelperError('Both arguments must be provided.');
+                }
+                return arg1.toString() === arg2.toString();
+            },
+            hint: 'Usage: {{equals arg1 arg2}}'
         },
         {
             keyword: 'and',
@@ -30,7 +44,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Runs the comparison `arg1 && arg2`, and returns the result.',
                 fr: 'Exécute la comparaison `arg1 && arg2`, et retourne le résultat.'
             },
-            callback: (arg1, arg2) => arg1 && arg2
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [arg1, arg2] = args;
+                return arg1 && arg2;
+            },
+            hint: 'Usage: {{and arg1 arg2}}'
         },
         {
             keyword: 'or',
@@ -38,7 +57,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Runs the comparison `arg1 || arg2`, and returns the result.',
                 fr: 'Exécute la comparaison `arg1 || arg2`, et retourne le résultat.'
             },
-            callback: (arg1, arg2) => arg1 || arg2
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [arg1, arg2] = args;
+                return arg1 || arg2;
+            },
+            hint: 'Usage: {{or arg1 arg2}}'
         },
         {
             keyword: 'not',
@@ -46,7 +70,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Runs the comparison `!arg`, and returns the result.',
                 fr: 'Exécute la comparaison `!arg`, et retourne le résultat.'
             },
-            callback: arg => !arg
+            callback: (...args) => {
+                args.pop(); // remove options
+                const arg = args[0];
+                return !arg;
+            },
+            hint: 'Usage: {{not arg}}'
         },
         {
             keyword: 'curly',
@@ -54,7 +83,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Wraps the given argument in curly braces.',
                 fr: "Entoure l'argument donné d'accolades."
             },
-            callback: arg1 => new Handlebars.SafeString(`{{${arg1}}}`)
+            callback: (...args) => {
+                args.pop(); // remove options
+                const arg1 = args[0];
+                return new Handlebars.SafeString(`{{${arg1}}}`);
+            },
+            hint: 'Usage: {{curly arg}}'
         },
         {
             keyword: 'join',
@@ -62,7 +96,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Joins two string arguments with a given string `sep`, or the empty string as a default.',
                 fr: 'Joint deux arguments de chaîne avec une chaîne donnée `sep`, ou la chaîne vide par défaut.'
             },
-            callback: (arg1, arg2, context) => [arg1?.toString() ?? '', arg2?.toString() ?? ''].join(context.hash?.sep ?? '')
+            callback: (...args) => {
+                const context = args.pop();
+                const [arg1, arg2] = args;
+                return [arg1?.toString() ?? '', arg2?.toString() ?? ''].join(context.hash?.sep ?? '');
+            },
+            hint: 'Usage: {{join arg1 arg2 sep=string}}'
         },
         {
             keyword: 'upper',
@@ -70,7 +109,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Returns the uppercase representation of a string argument.',
                 fr: "Retourne la représentation en majuscules d'un argument de chaîne."
             },
-            callback: (val) => val.toLocaleUpperCase()
+            callback: (...args) => {
+                args.pop(); // remove options
+                const val = args[0];
+                if (isNil(val)) {
+                    throw new HowlerHelperError('Upper expects a string argument');
+                }
+                return val.toString().toLocaleUpperCase();
+            },
+            hint: 'Usage: {{upper val}}'
         },
         {
             keyword: 'lower',
@@ -78,7 +125,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Returns the lowercase representation of a string argument.',
                 fr: "Retourne la représentation en minuscules d'un argument de chaîne."
             },
-            callback: (val) => val.toLocaleLowerCase()
+            callback: (...args) => {
+                args.pop(); // remove options
+                const val = args[0];
+                if (isNil(val)) {
+                    throw new HowlerHelperError('Lower expects a string argument');
+                }
+                return val.toString().toLocaleLowerCase();
+            },
+            hint: 'Usage: {{lower val}}'
         },
         {
             keyword: 'fetch',
@@ -87,7 +142,9 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 fr: "Récupère l'URL fournie et retourne la clé donnée (aplatie) de l'objet JSON retourné. Notez que le résultat doit être du JSON !"
             },
             async: true,
-            callback: async (url, key) => {
+            callback: async (...args) => {
+                args.pop(); // remove options
+                const [url, key] = args;
                 try {
                     if (!FETCH_RESULTS[url]) {
                         FETCH_RESULTS[url] = fetch(url).then(res => res.json());
@@ -98,7 +155,8 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 catch (e) {
                     return '';
                 }
-            }
+            },
+            hint: 'Usage: {{fetch url key}}'
         },
         {
             keyword: 'howler',
@@ -106,12 +164,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Given a howler hit ID, this helper renders a hit card for that ID.',
                 fr: 'Étant donné un ID de résultat howler, cet assistant affiche une carte de résultat pour cet ID.'
             },
-            componentCallback: id => {
+            componentCallback: (...args) => {
+                args.pop(); // remove options
+                const id = args[0];
                 if (!id) {
                     return _jsx(AppListEmpty, {});
                 }
                 return _jsx(HitCard, { id: id, layout: HitLayout.NORMAL });
-            }
+            },
+            hint: 'Usage: {{howler hitId}}'
         },
         {
             keyword: 'entries',
@@ -119,12 +180,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Given a dict, return an array of {key, value} objects.',
                 fr: "Étant donné un dictionnaire, retourne un tableau d'objets {key, value}."
             },
-            callback: obj => {
+            callback: (...args) => {
+                args.pop(); // remove options
+                const obj = args[0];
                 if (!isObject(obj)) {
                     return new Handlebars.SafeString('Invalid Object.');
                 }
                 return Object.entries(obj).map(([key, value]) => ({ key, value }));
-            }
+            },
+            hint: 'Usage: {{entries obj}}'
         },
         {
             keyword: 'render_json',
@@ -132,12 +196,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Given JSON data, this helper renders a JSON viewer component.',
                 fr: 'Étant donné des données JSON, cet assistant affiche un composant de visualisation JSON.'
             },
-            componentCallback: data => {
+            componentCallback: (...args) => {
+                args.pop(); // remove options
+                const data = args[0];
                 if (!data) {
                     return _jsx(AppListEmpty, {});
                 }
                 return _jsx(JSONViewer, { data: data });
-            }
+            },
+            hint: 'Usage: {{render_json obj}}'
         },
         {
             keyword: 'to_json',
@@ -145,9 +212,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Convert any object into a JSON string.',
                 fr: "Convertit n'importe quel objet en chaîne JSON."
             },
-            callback: obj => {
+            callback: (...args) => {
+                args.pop(); // remove options
+                const obj = args[0];
                 return new Handlebars.SafeString(JSON.stringify(obj));
-            }
+            },
+            hint: 'Usage: {{to_json obj}}'
         },
         {
             keyword: 'parse_json',
@@ -155,9 +225,20 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Convert a JSON string into an object.',
                 fr: 'Convertit une chaîne JSON en objet.'
             },
-            callback: str => {
-                return JSON.parse(str);
-            }
+            callback: (...args) => {
+                args.pop(); // remove options
+                const str = args[0];
+                if (isNil(str)) {
+                    throw new HowlerHelperError('Parse JSON expects a string argument');
+                }
+                try {
+                    return JSON.parse(str);
+                }
+                catch (e) {
+                    throw new HowlerHelperError('Invalid JSON string');
+                }
+            },
+            hint: 'Usage: {{parse_json str}}'
         },
         {
             keyword: 'get',
@@ -165,14 +246,17 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Returns the given (flattened) key from the provided object.',
                 fr: "Retourne la clé donnée (aplatie) de l'objet fourni."
             },
-            callback: (data, key) => {
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [data, key] = args;
                 try {
                     return get(data, key);
                 }
                 catch (e) {
                     return '';
                 }
-            }
+            },
+            hint: 'Usage: {{get obj key}}'
         },
         {
             keyword: 'includes',
@@ -180,9 +264,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Checks if field is in string',
                 fr: 'Vérifie si le champ est dans la chaîne'
             },
-            callback: (arg1, arg2) => {
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [arg1, arg2] = args;
                 return !!arg2 && !!arg1?.includes(arg2);
-            }
+            },
+            hint: 'Usage: {{includes str substr}}'
         },
         {
             keyword: 'table',
@@ -190,7 +277,9 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Render a table in markdown given an array of cells',
                 fr: "Affiche un tableau en markdown à partir d'un tableau de cellules"
             },
-            componentCallback: (cells) => {
+            componentCallback: (...args) => {
+                args.pop(); // remove options
+                const cells = args[0];
                 const columns = Object.keys(groupBy(cells, 'column'));
                 const rows = groupBy(cells, 'row');
                 return (_jsx(Paper, { sx: { width: '95%', overflowX: 'auto', m: 1 }, children: _jsxs(Table, { children: [_jsx(TableHead, { children: _jsx(TableRow, { children: columns.map(col => (_jsx(TableCell, { sx: { maxWidth: '150px' }, children: col
@@ -202,7 +291,8 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                                             return _jsx(TableCell, { children: cell?.value ?? 'N/A' }, col + cell?.value);
                                         }) }, rowId));
                                 }) })] }) }));
-            }
+            },
+            hint: 'Usage: {{table cells}}'
         },
         {
             keyword: 'action',
@@ -210,9 +300,12 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: 'Execute a howler action given a specific action ID (from the URL when viewing the action, i.e. yaIKVqiKhWpyCsWdqsE4D)',
                 fr: "Exécute une action howler à partir d'un ID d'action spécifique (de l'URL lors de la visualisation de l'action, par ex. yaIKVqiKhWpyCsWdqsE4D)"
             },
-            componentCallback: (actionId, hitId, context) => {
+            componentCallback: (...args) => {
+                const context = args.pop(); // remove options
+                const [actionId, hitId] = args;
                 return _jsx(ActionButton, { actionId: actionId, hitId: hitId, ...(context.hash ?? {}) });
-            }
+            },
+            hint: 'Usage: {{action actionId hitId}}'
         },
         {
             keyword: 'replace',
@@ -220,9 +313,15 @@ export const useHelpers = (opts = { async: true, components: true }) => {
                 en: '',
                 fr: ''
             },
-            callback: (str, searchValue, replaceValue) => {
-                return str.replaceAll(searchValue ?? '', replaceValue ?? '');
-            }
+            callback: (...args) => {
+                args.pop(); // remove options
+                const [str, searchValue, replaceValue] = args;
+                if (isNil(str) || isNil(searchValue) || isNil(replaceValue)) {
+                    throw new HowlerHelperError('Replace expects three arguments');
+                }
+                return str.toString().replaceAll(searchValue ?? '', replaceValue ?? '');
+            },
+            hint: 'Usage: {{replace str searchValue replaceValue}}'
         },
         ...howlerPluginStore.plugins.flatMap(plugin => pluginStore.executeFunction(`${plugin}.helpers`))
     ].filter((entry) => (opts.async || !entry.async) && (opts.components || !entry.componentCallback)), [opts.async, opts.components, pluginStore]);

package/package.json

@@ -12,7 +12,7 @@
     ]
   },
   "dependencies": {
-    "@cccsaurora/clue-ui": "1.2.8",
+    "@cccsaurora/clue-ui": "1.3.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^7.0.0",
     "@dnd-kit/sortable": "^8.0.0",
@@ -34,9 +34,9 @@
     "chartjs-adapter-dayjs-4": "^1.0.4",
     "chartjs-plugin-zoom": "^2.2.0",
     "dayjs": "^1.11.21",
-    "dompurify": "^3.4.11",
+    "dompurify": "^3.4.12",
     "flat": "^6.0.1",
-    "fuse.js": "^7.4.2",
+    "fuse.js": "^7.5.0",
     "handlebars": "^4.7.9",
     "handlebars-async-helpers": "^1.0.6",
     "i18next": "^23.16.8",
@@ -93,7 +93,7 @@
     "url": "https://github.com/CybercentreCanada/howler"
   },
   "type": "module",
-  "version": "2.19.0-dev.1260",
+  "version": "2.19.0-dev.1266",
   "exports": {
     "./i18n": "./i18n.js",
     "./index.css": "./index.css",