@researchdatabox/sails-ng-common 0.2.0 → 5.0.0-RC1

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

@@ -0,0 +1,258 @@
+import Handlebars from 'handlebars';
+/**
+ * Helper function definitions that can be registered with Handlebars.
+ * Each function is a pure, deterministic helper that does not execute arbitrary code.
+ */
+export declare const handlebarsHelperDefinitions: {
+    /**
+     * Format a date value using a custom format string.
+     * 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"}}
+     */
+    formatDate: (dateValue: string | Date, formatOrOptions?: string | Record<string, unknown>) => string;
+    /**
+     * Format a date value using locale-aware presets.
+     * Supports ISO date strings and JavaScript Date instances.
+     *
+     * @example {{formatDateLocale lastSaveDate "DATETIME_MED"}}
+     */
+    formatDateLocale: (dateValue: string | Date, presetNameOrOptions?: string | Record<string, unknown>, localeOrOptions?: string | Record<string, unknown>) => string;
+    /**
+     * Parse a date string (pass-through for chaining).
+     *
+     * @example {{parseDateString dateString}}
+     */
+    parseDateString: (dateString: string) => string;
+    /**
+     * Get a nested property from an object using dot notation.
+     * Replaces lodash template usage like: ${ _.get(data, 'metadata.contributor_ci', '') }
+     *
+     * @example {{get this "metadata.contributor_ci.text_full_name"}}
+     */
+    get: (obj: unknown, path: string, defaultValue?: unknown) => unknown;
+    /**
+     * Check if a value is empty (null, undefined, empty string, empty array, empty object).
+     *
+     * @example {{#if (isEmpty value)}}empty{{/if}}
+     */
+    isEmpty: (value: unknown) => boolean;
+    /**
+     * Check if a value is undefined.
+     *
+     * @example {{#if (isUndefined value)}}undefined{{/if}}
+     */
+    isUndefined: (value: unknown) => boolean;
+    /**
+     * Check if a value is null.
+     *
+     * @example {{#if (isNull value)}}null{{/if}}
+     */
+    isNull: (value: unknown) => boolean;
+    /**
+     * Check if a value is defined (not undefined and not null).
+     *
+     * @example {{#if (isDefined value)}}defined{{/if}}
+     */
+    isDefined: (value: unknown) => boolean;
+    /**
+     * Check if a value is an array.
+     *
+     * @example {{#if (isArray value)}}is array{{/if}}
+     */
+    isArray: (value: unknown) => boolean;
+    /**
+     * Check if a value is a plain object.
+     *
+     * @example {{#if (isObject value)}}is object{{/if}}
+     */
+    isObject: (value: unknown) => boolean;
+    /**
+     * Strict equality comparison.
+     *
+     * @example {{#if (eq status "active")}}active{{/if}}
+     */
+    eq: (a: unknown, b: unknown) => boolean;
+    /**
+     * Not equal comparison.
+     *
+     * @example {{#if (ne status "inactive")}}not inactive{{/if}}
+     */
+    ne: (a: unknown, b: unknown) => boolean;
+    /**
+     * Logical AND - returns true if all arguments are truthy.
+     * Note: The last argument is the Handlebars options hash, which is removed.
+     *
+     * @example {{#if (and condition1 condition2)}}both true{{/if}}
+     */
+    and: (...args: unknown[]) => boolean;
+    /**
+     * Logical OR - returns true if any argument is truthy.
+     * Note: The last argument is the Handlebars options hash, which is removed.
+     *
+     * @example {{#if (or condition1 condition2)}}at least one true{{/if}}
+     */
+    or: (...args: unknown[]) => boolean;
+    /**
+     * Logical NOT - returns true if value is falsy.
+     *
+     * @example {{#if (not condition)}}condition is false{{/if}}
+     */
+    not: (value: unknown) => boolean;
+    /**
+     * Greater than comparison.
+     *
+     * @example {{#if (gt count 0)}}has items{{/if}}
+     */
+    gt: (a: unknown, b: unknown) => boolean;
+    /**
+     * Greater than or equal comparison.
+     *
+     * @example {{#if (gte count 1)}}at least one{{/if}}
+     */
+    gte: (a: unknown, b: unknown) => boolean;
+    /**
+     * Less than comparison.
+     *
+     * @example {{#if (lt count 10)}}less than ten{{/if}}
+     */
+    lt: (a: unknown, b: unknown) => boolean;
+    /**
+     * Less than or equal comparison.
+     *
+     * @example {{#if (lte count 10)}}ten or less{{/if}}
+     */
+    lte: (a: unknown, b: unknown) => boolean;
+    /**
+     * Trim leading/trailing whitespace from a string value.
+     *
+     * @example {{trim title}}
+     */
+    trim: (value: unknown) => string;
+    /**
+     * Convert a value to lowercase text.
+     *
+     * @example {{toLower value}}
+     */
+    toLower: (value: unknown) => string;
+    /**
+     * Convert a value to uppercase text.
+     *
+     * @example {{toUpper value}}
+     */
+    toUpper: (value: unknown) => string;
+    /**
+     * Translation helper - looks up translation from context.translationService.
+     * The translation service must be provided in the template context.
+     *
+     * @example {{t "label.title"}}
+     */
+    t: (this: {
+        translationService?: {
+            t: (key: string) => string;
+        };
+    }, key: string) => string;
+    /**
+     * Join array elements with a separator.
+     *
+     * @example {{join items ", "}}
+     */
+    join: (arr: unknown[], separator?: string) => string;
+    /**
+     * Extract a property 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") ","}}.
+     *
+     * @example {{join (pluck record.metadata.creators "email") ","}}
+     */
+    pluck: (arr: unknown, path: string) => unknown[];
+    /**
+     * Return part of a string using slice semantics.
+     *
+     * @example {{substring notation 0 6}}
+     */
+    substring: (value: unknown, start: number, end?: number) => string;
+    /**
+     * Split a string into parts, or return one part if index is provided.
+     * Supports negative index values, where -1 is the last part.
+     *
+     * @example {{split notation "/" -1}}
+     */
+    split: (value: unknown, separator: string, index?: number) => unknown;
+    /**
+     * Encode user-controlled URL path values while preserving path separators.
+     * Trailing slashes are trimmed so prefixed paths can be safely concatenated.
+     *
+     * @example {{urlEncode oid}}
+     */
+    urlEncode: (value: unknown) => string;
+    /**
+     * Concatenate strings.
+     * Note: The last argument is the Handlebars options hash, which is removed.
+     *
+     * @example {{concat prefix value suffix}}
+     */
+    concat: (...args: unknown[]) => string;
+    /**
+     * Default value if the primary value is empty/falsy.
+     *
+     * @example {{default title "Untitled"}}
+     */
+    default: (value: unknown, defaultValue: unknown) => unknown;
+    /**
+     * Convert markdown to HTML when output format is markdown, otherwise pass HTML through.
+     * Note: This helper does not sanitize HTML output, we are currently only using it on the client side with Angular's DomSanitizer to ensure safe usage.
+     * Do not use this helper with untrusted content in a server-side context without proper sanitization (see DOMSanitizerService as a way to sanitize the HTML on the server side).
+     *
+     * @example {{{markdownToHtml content outputFormat}}}
+     */
+    markdownToHtml: (value: unknown, outputFormat?: string) => string;
+    /**
+     * Render plain text as escaped HTML while preserving line breaks.
+     *
+     * @example {{{plaintextToHtml content}}}
+     */
+    plaintextToHtml: (value: unknown) => string;
+    /**
+     * JSON stringify a value (useful for debugging).
+     *
+     * @example {{json data}}
+     */
+    json: (value: unknown) => string;
+    /**
+     * Render metadata values into nested HTML suitable for generated view-only display.
+     *
+     * @example {{{renderMetadataValue metadata.someField}}}
+     */
+    renderMetadataValue: (value: unknown) => string;
+    /**
+     * Build a view-mode download URL for a file upload attachment value.
+     *
+     * @example {{attachmentDownloadUrl this oid branding portal}}
+     */
+    attachmentDownloadUrl: (attachment: unknown, oid: unknown, branding: unknown, portal: unknown) => string;
+};
+/**
+ * Register Handlebars helpers for use in dashboard and report templates.
+ * Uses shared helpers from sails-ng-common for consistency between server and client.
+ */
+export declare function handlebarsInstance(): typeof Handlebars;
+/**
+ * Pre-compile a handlebars template.
+ * @param input The template to compile.
+ * @param options The compile options.
+ */
+export declare function handlebarsPrecompile(input: unknown, options?: PrecompileOptions): TemplateSpecification;
+/**
+ * Get a compiled handlebars template.
+ * @param input The template to compile.
+ * @param options The compile options.
+ */
+export declare function handlebarsCompile(input: unknown, options?: CompileOptions): HandlebarsTemplateDelegate;
+/**
+ * Render a pre-compiled handlebars template.
+ * @param precompilation The pre-compiled template.
+ */
+export declare function handlebarsTemplate(precompilation: TemplateSpecification): HandlebarsTemplateDelegate;