@researchdatabox/sails-ng-common 5.1.0-beta.12573 → 5.1.0-beta.13939

package/dist/src/handlebars-helpers.d.ts

@@ -1,7 +1,16 @@
 import Handlebars from 'handlebars';
+export declare const dateModifyOperations: readonly ["startOf", "endOf", "plus"];
+export declare const dateModifyShiftUnits: readonly ["year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond"];
+export declare const dateModifyPlusUnits: readonly ["years", "quarters", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds"];
+export type DateModifyOperations = (typeof dateModifyOperations)[number];
 /**
  * Helper function definitions that can be registered with Handlebars.
  * Each function is a pure, deterministic helper that does not execute arbitrary code.
+ *
+ * These functions return an appropriate empty value, or the first value, when given unexpected arguments, instead of throwing an error.
+ * Templates can be edited by users, and we want to validate where the user is editing and be able to show the rendered content.
+ *
+ * All functions must allow for a handlebars options object as the last argument.
  */
 export declare const handlebarsHelperDefinitions: {
     /**
@@ -9,9 +18,11 @@ export declare const handlebarsHelperDefinitions: {
      * Supports ISO date strings and JavaScript Date instances.
      * Replaces lodash template usage like: ${ DateTime.fromISO(data.date).toFormat('dd/MM/yyyy hh:mm a') }
      *
-     * @example {{formatDate lastSaveDate "dd/MM/yyyy hh:mm a"}}
+     * An explicit zone changes the display zone while preserving the instant.
+     * Without a zone, existing host-zone formatting is retained.
+     * @example {{formatDate lastSaveDate "dd/MM/yyyy hh:mm a" "Australia/Sydney"}}
      */
-    formatDate: (dateValue: string | Date, formatOrOptions?: string | Record<string, unknown>) => string;
+    formatDate: (dateValue: string | Date, formatOrOptions?: string | Record<string, unknown>, zoneOrOptions?: string | Record<string, unknown>) => string;
     /**
      * Format a date value using locale-aware presets.
      * Supports ISO date strings and JavaScript Date instances.
@@ -25,6 +36,23 @@ export declare const handlebarsHelperDefinitions: {
      * @example {{parseDateString dateString}}
      */
     parseDateString: (dateString: string) => string;
+    /**
+     * Modify a date by adding the provided time units, or setting to the start or end of the given time unit.
+     * Supports ISO date strings and JavaScript Date instances.
+     *
+     * The parsed date time uses the specified offset, or 'UTC' otherwise.
+     * The date time is then converted to UTC.
+     * Use formatDate or formatDateLocale to format date for display.
+     *
+     * Returns a new date value with the described change applied.
+     * Returns the first provided argument unchanged if the call was not valid.
+     * Returns empty string if no arguments were provided.
+     * @param args The arguments to set the operation, duration units, and duration values.
+     *    1. The date value to modify or handlebars options.
+     *    2. Then the first 'plus' operation duration unit, or the operation name, or the handlebars options.
+     *    3. Then the duration unit, or duration value (allows multiple pairs), or handlebars options.
+     */
+    dateModify: (...args: unknown[]) => string | Date | unknown;
     /**
      * Get a nested property from an object using dot notation.
      * Replaces lodash template usage like: ${ _.get(data, 'metadata.contributor_ci', '') }
@@ -102,42 +130,56 @@ export declare const handlebarsHelperDefinitions: {
     not: (value: unknown) => boolean;
     /**
      * Greater than comparison.
+     * Returns false if the comparison cannot be performed.
      *
      * @example {{#if (gt count 0)}}has items{{/if}}
      */
     gt: (a: unknown, b: unknown) => boolean;
     /**
      * Greater than or equal comparison.
+     * Returns false if the comparison cannot be performed.
      *
      * @example {{#if (gte count 1)}}at least one{{/if}}
      */
     gte: (a: unknown, b: unknown) => boolean;
     /**
      * Less than comparison.
+     * Returns false if the comparison cannot be performed.
      *
      * @example {{#if (lt count 10)}}less than ten{{/if}}
      */
     lt: (a: unknown, b: unknown) => boolean;
     /**
      * Less than or equal comparison.
+     * Returns false if the comparison cannot be performed.
      *
      * @example {{#if (lte count 10)}}ten or less{{/if}}
      */
     lte: (a: unknown, b: unknown) => boolean;
     /**
      * Trim leading/trailing whitespace from a string value.
+     * Returns input value converted to a string for non-string input.
      *
      * @example {{trim title}}
      */
     trim: (value: unknown) => string;
+    /**
+     * Trim leading and trailing whitespace from each string item in an array.
+     * @example {{trimArray ['  value ', 0]}} -> ['value', 0]
+     * @example {{trimArray {aProp: ['value']}}} -> {aProp: ['value']}
+     * @param value
+     */
+    trimArray: (value: unknown) => string[] | unknown;
     /**
      * Convert a value to lowercase text.
+     * Returns input value converted to a string for non-string input.
      *
      * @example {{toLower value}}
      */
     toLower: (value: unknown) => string;
     /**
      * Convert a value to uppercase text.
+     * Returns input value converted to a string for non-string input.
      *
      * @example {{toUpper value}}
      */
@@ -160,14 +202,17 @@ export declare const handlebarsHelperDefinitions: {
      */
     join: (arr: unknown[], separator?: string) => string;
     /**
-     * Extract a property from each item in an array using dot notation.
+     * Extract one or more properties from each item in an array using dot notation.
      * Replaces lodash usage like: _.map(creators, c => c.email).
      * Returns an empty array for non-array input. Combine with {{join}} to
      * build a delimited string, e.g. {{join (pluck creators "email") ","}}.
      *
+     * For one property, returns an array of the property values.
+     * For more than one property, returns an array of arrays containing the specified property values in the same order.
+     *
      * @example {{join (pluck record.metadata.creators "email") ","}}
      */
-    pluck: (arr: unknown, path: string) => unknown[];
+    pluck: (...args: unknown[]) => unknown[];
     /**
      * Return part of a string using slice semantics.
      *
@@ -233,6 +278,82 @@ export declare const handlebarsHelperDefinitions: {
      * @example {{attachmentDownloadUrl this oid branding portal}}
      */
     attachmentDownloadUrl: (attachment: unknown, oid: unknown, branding: unknown, portal: unknown) => string;
+    /**
+     * Convert a value with an unknown type to an array.
+     * With one value, ensures it is an array.
+     * With more than one value, returns all values in an array.
+     * Does not flatten nested arrays.
+     *
+     * @example {{asArray ['value']}} -> ['value]
+     * @example {{asArray 'value'}} -> ['value']
+     * @example {{asArray {aProp: 'value'} null 0 ['value']}} -> [{aProp: 'value'}, null, 0, ['value']]
+     * @param args The values to get as an array.
+     */
+    asArray: (...args: unknown[]) => unknown[];
+    /**
+     * Convert a value with an unknown type to an array.
+     * With one value, ensures it is an array.
+     * With more than one value, returns all values in an array.
+     * Flattens nested arrays to depth 1. Use multiple times to flatten deeply nested arrays.
+     *
+     * @example {{flattenArray ['value']}} -> ['value]
+     * @example {{flattenArray 'value'}} -> ['value']
+     * @example {{flattenArray {aProp: 'value'} null 0 ['value']}} -> [{aProp: 'value'}, null, 0, 'value']
+     * @example {{flattenArray {aProp: 'value'} null 0 [['value']]}} -> [{aProp: 'value'}, null, 0, ['value']]
+     * @example {{flattenArray [{aProp: 'value'} null 0 ['value']]}} -> [{aProp: 'value'}, null, 0, 'value']
+     * @param args
+     */
+    flattenArray: (...args: unknown[]) => unknown[];
+    /**
+     * Remove undefined, null, and empty trimmed strings from an array.
+     * When provided a non-array value, returns it unchanged.
+     *
+     * @example {{filterArray ['one', '  ', undefined, null, {}]}} -> ['one', {}]
+     * @example {{filterArray undefined}} -> undefined
+     * @param value The array to filter.
+     */
+    filterArray: (value: unknown) => unknown[] | unknown;
+    /**
+     * Build a display name from a contributor object.
+     * Returns empty string if the value is not a plain object.
+     * The provided path options will be checked in order, and the first that has a truthy value will be used.
+     * @example {{displayName {text_full_name: 'My Name'} }} -> 'My Name'
+     * @example {{displayName {given_name: 'given', family_name: 'family'} }} -> 'given family'
+     * @param value Contributor object.
+     * @param fullOrOptions Paths to use as full name.
+     * @param honorificOrOptions Paths to use as honorific.
+     * @param givenOrOptions Paths to use as given name.
+     * @param familyOrOptions Paths to use as family name.
+     */
+    displayName: (value: unknown, fullOrOptions?: string[], honorificOrOptions?: string[], givenOrOptions?: string[], familyOrOptions?: string[]) => string;
+    /**
+     * Build a display name from a contributor object for each item in an array.
+     * Returns empty string if the value is not a plain object.
+     * The provided path options will be checked in order, and the first that has a truthy value will be used.
+     * @example {{displayNameArray [{text_full_name: 'My Name'}] }} -> ['My Name']
+     * @example {{displayNameArray [{given_name: 'given', family_name: 'family'}] }} -> ['given family']
+     * @param value Array of contributor objects.
+     * @param fullOrOptions Paths to use as full name.
+     * @param honorificOrOptions Paths to use as honorific.
+     * @param givenOrOptions Paths to use as given name.
+     * @param familyOrOptions Paths to use as family name.
+     */
+    displayNameArray: (value: unknown, fullOrOptions?: string[], honorificOrOptions?: string[], givenOrOptions?: string[], familyOrOptions?: string[]) => string[] | unknown;
+    /**
+     * Create a new array with items case-insensitive sorted order.
+     * A non-array argument is returned without changes.
+     * @example {{sort ['value2', 'value1']}} -> ['value1', 'value2']
+     * @example {{sort {text_full_name: 'My Name'} }} -> {text_full_name: 'My Name'}
+     * @param value
+     */
+    sort: (value: unknown) => any[] | unknown;
+    /**
+     * Remove duplicate strings from an array.
+     * Non-string duplicate entries are kept.
+     * A non-array is returned without changes.
+     * @param value
+     */
+    unique: (value: unknown) => string[] | unknown;
 };
 /**
  * Register Handlebars helpers for use in dashboard and report templates.