feat(editor): Autocomplete info box: improve structure and add examples (#9019)

Co-authored-by: Giulio Andreini <andreini@netseven.it>

packages/workflow/src/Extensions/StringExtensions.ts

@@ -265,6 +265,16 @@ function toFloat(value: string) {
 	return float;
 }
 
+function toNumber(value: string) {
+	const num = Number(value.replace(CURRENCY_REGEXP, ''));
+
+	if (isNaN(num)) {
+		throw new ExpressionExtensionError('cannot convert to number');
+	}
+
+	return num;
+}
+
 function quote(value: string, extraArgs: string[]) {
 	const [quoteChar = '"'] = extraArgs;
 	return `${quoteChar}${value
@@ -405,20 +415,22 @@ function base64Decode(value: string): string {
 
 removeMarkdown.doc = {
 	name: 'removeMarkdown',
-	description: 'Removes Markdown formatting from a string.',
+	description: 'Removes any Markdown formatting from the string. Also removes HTML tags.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-removeMarkdown',
+	examples: [{ example: '"*bold*, [link]()".removeMarkdown()', evaluated: '"bold, link"' }],
 };
 
 removeTags.doc = {
 	name: 'removeTags',
-	description: 'Removes tags, such as HTML or XML, from a string.',
+	description: 'Removes tags, such as HTML or XML, from the string.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-removeTags',
+	examples: [{ example: '"<b>bold</b>, <a>link</a>".removeTags()', evaluated: '"bold, link"' }],
 };
 
 toDate.doc = {
@@ -432,20 +444,34 @@ toDate.doc = {
 
 toDateTime.doc = {
 	name: 'toDateTime',
-	description: 'Converts a string to a Luxon DateTime.',
+	description:
+		'Converts the string to a DateTime. Useful for further transformation. Supported formats for the string are ISO 8601, HTTP, RFC2822, SQL and Unix timestamp in milliseconds. To parse other formats, use <a target="_blank" href=”https://moment.github.io/luxon/api-docs/index.html#datetimefromformat”> <code>DateTime.fromFormat()</code></a>.',
 	section: 'cast',
 	returnType: 'DateTime',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-toDateTime',
+	examples: [
+		{ example: '"2024-03-29T18:06:31.798+01:00".toDateTime()' },
+		{ example: '"Fri, 29 Mar 2024 18:08:01 +0100".toDateTime()' },
+		{ example: '"20240329".toDateTime()' },
+		{ example: '"1711732132990".toDateTime()' },
+	],
 };
 
 toBoolean.doc = {
 	name: 'toBoolean',
-	description: 'Converts a string to a boolean.',
+	description:
+		'Converts the string to a boolean value. <code>0</code>, <code>false</code> and <code>no</code> resolve to <code>false</code>, everything else to <code>true</code>. Case-insensitive.',
 	section: 'cast',
 	returnType: 'boolean',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-toBoolean',
+	examples: [
+		{ example: '"true".toBoolean()', evaluated: 'true' },
+		{ example: '"false".toBoolean()', evaluated: 'false' },
+		{ example: '"0".toBoolean()', evaluated: 'false' },
+		{ example: '"hello".toBoolean()', evaluated: 'true' },
+	],
 };
 
 toFloat.doc = {
@@ -454,6 +480,7 @@ toFloat.doc = {
 	section: 'cast',
 	returnType: 'number',
 	aliases: ['toDecimalNumber'],
+	hidden: true,
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-toDecimalNumber',
 };
@@ -465,12 +492,15 @@ toInt.doc = {
 	returnType: 'number',
 	args: [{ name: 'radix?', type: 'number' }],
 	aliases: ['toWholeNumber'],
+	hidden: true,
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-toInt',
 };
 
 toSentenceCase.doc = {
 	name: 'toSentenceCase',
-	description: 'Formats a string to sentence case. Example: "This is a sentence".',
+	description:
+		'Changes the capitalization of the string to sentence case. The first letter of each sentence is capitalized and all others are lowercased.',
+	examples: [{ example: '"quick! brown FOX".toSentenceCase()', evaluated: '"Quick! Brown fox"' }],
 	section: 'case',
 	returnType: 'string',
 	docURL:
@@ -479,7 +509,9 @@ toSentenceCase.doc = {
 
 toSnakeCase.doc = {
 	name: 'toSnakeCase',
-	description: 'Formats a string to snake case. Example: "this_is_snake_case".',
+	description:
+		'Changes the format of the string to snake case. Spaces and dashes are replaced by <code>_</code>, symbols are removed and all letters are lowercased.',
+	examples: [{ example: '"quick brown $FOX".toSnakeCase()', evaluated: '"quick_brown_fox"' }],
 	section: 'case',
 	returnType: 'string',
 	docURL:
@@ -489,7 +521,8 @@ toSnakeCase.doc = {
 toTitleCase.doc = {
 	name: 'toTitleCase',
 	description:
-		'Formats a string to title case. Example: "This Is a Title". Will not change already uppercase letters to prevent losing information from acronyms and trademarks such as iPhone or FAANG.',
+		"Changes the capitalization of the string to title case. The first letter of each word is capitalized and the others left unchanged. Short prepositions and conjunctions aren't capitalized (e.g. 'a', 'the').",
+	examples: [{ example: '"quick a brown FOX".toTitleCase()', evaluated: '"Quick a Brown Fox"' }],
 	section: 'case',
 	returnType: 'string',
 	docURL:
@@ -498,31 +531,60 @@ toTitleCase.doc = {
 
 urlEncode.doc = {
 	name: 'urlEncode',
-	description: 'Encodes a string to be used/included in a URL.',
+	description:
+		'Encodes the string so that it can be used in a URL. Spaces and special characters are replaced with codes of the form <code>%XX</code>.',
 	section: 'edit',
-	args: [{ name: 'entireString?', type: 'boolean' }],
+	args: [
+		{
+			name: 'allChars',
+			optional: true,
+			description:
+				'Whether to encode characters that are part of the URI syntax (e.g. <code>=</code>, <code>?</code>)',
+			default: 'false',
+			type: 'boolean',
+		},
+	],
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-urlEncode',
+	examples: [
+		{ example: '"name=Nathan Automat".urlEncode()', evaluated: '"name%3DNathan%20Automat"' },
+		{ example: '"name=Nathan Automat".urlEncode(true)', evaluated: '"name=Nathan%20Automat"' },
+	],
 };
 
 urlDecode.doc = {
 	name: 'urlDecode',
 	description:
-		'Decodes a URL-encoded string. It decodes any percent-encoded characters in the input string, and replaces them with their original characters.',
+		'Decodes a URL-encoded string. Replaces any character codes in the form of <code>%XX</code> with their corresponding characters.',
+	args: [
+		{
+			name: 'allChars',
+			optional: true,
+			description:
+				'Whether to decode characters that are part of the URI syntax (e.g. <code>=</code>, <code>?</code>)',
+			default: 'false',
+			type: 'boolean',
+		},
+	],
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-urlDecode',
+	examples: [
+		{ example: '"name%3DNathan%20Automat".urlDecode()', evaluated: '"name=Nathan Automat"' },
+		{ example: '"name%3DNathan%20Automat".urlDecode(true)', evaluated: '"name%3DNathan Automat"' },
+	],
 };
 
 replaceSpecialChars.doc = {
 	name: 'replaceSpecialChars',
-	description: 'Replaces non-ASCII characters in a string with an ASCII representation.',
+	description: 'Replaces special characters in the string with the closest ASCII character',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-replaceSpecialChars',
+	examples: [{ example: '"déjà".replaceSpecialChars()', evaluated: '"deja"' }],
 };
 
 length.doc = {
@@ -536,122 +598,199 @@ length.doc = {
 
 isDomain.doc = {
 	name: 'isDomain',
-	description: 'Checks if a string is a domain.',
+	description: 'Returns <code>true</code> if a string is a domain.',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isDomain',
+	examples: [
+		{ example: '"n8n.io".isDomain()', evaluated: 'true' },
+		{ example: '"http://n8n.io".isDomain()', evaluated: 'false' },
+		{ example: '"hello".isDomain()', evaluated: 'false' },
+	],
 };
 
 isEmail.doc = {
 	name: 'isEmail',
-	description: 'Checks if a string is an email.',
+	description: 'Returns <code>true</code> if the string is an email.',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isEmail',
+	examples: [
+		{ example: '"me@example.com".isEmail()', evaluated: 'true' },
+		{ example: '"It\'s me@example.com".isEmail()', evaluated: 'false' },
+		{ example: '"hello".isEmail()', evaluated: 'false' },
+	],
 };
 
 isNumeric.doc = {
 	name: 'isNumeric',
-	description: 'Checks if a string only contains digits.',
+	description: 'Returns <code>true</code> if the string represents a number.',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isNumeric',
+	examples: [
+		{ example: '"1.2234".isNumeric()', evaluated: 'true' },
+		{ example: '"hello".isNumeric()', evaluated: 'false' },
+		{ example: '"123E23".isNumeric()', evaluated: 'true' },
+	],
 };
 
 isUrl.doc = {
 	name: 'isUrl',
-	description: 'Checks if a string is a valid URL.',
+	description: 'Returns <code>true</code> if a string is a valid URL',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isUrl',
+	examples: [
+		{ example: '"https://n8n.io".isUrl()', evaluated: 'true' },
+		{ example: '"n8n.io".isUrl()', evaluated: 'false' },
+		{ example: '"hello".isUrl()', evaluated: 'false' },
+	],
 };
 
 isEmpty.doc = {
 	name: 'isEmpty',
-	description: 'Checks if a string is empty.',
+	description: 'Returns <code>true</code> if the string has no characters.',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isEmpty',
+	examples: [
+		{ example: '"".isEmpty()', evaluated: 'true' },
+		{ example: '"hello".isEmpty()', evaluated: 'false' },
+	],
 };
 
 isNotEmpty.doc = {
 	name: 'isNotEmpty',
-	description: 'Checks if a string has content.',
+	description: 'Returns <code>true</code> if the string has at least one character.',
 	section: 'validation',
 	returnType: 'boolean',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-isNotEmpty',
+	examples: [
+		{ example: '"hello".isNotEmpty()', evaluated: 'true' },
+		{ example: '"".isNotEmpty()', evaluated: 'false' },
+	],
 };
 
 extractEmail.doc = {
 	name: 'extractEmail',
-	description: 'Extracts an email from a string. Returns undefined if none is found.',
+	description:
+		'Extracts the first email found in the string. Returns <code>undefined</code> if none is found.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-extractEmail',
+	examples: [
+		{ example: '"My email is me@example.com".extractEmail()', evaluated: "'me@example.com'" },
+	],
 };
 
 extractDomain.doc = {
 	name: 'extractDomain',
 	description:
-		'Extracts a domain from a string containing a valid URL. Returns undefined if none is found.',
+		'If the string is an email address or URL, returns its domain (or <code>undefined</code> if nothing found). If the string also contains other content, try using <code>extractEmail()</code> or <code>extractUrl()</code> first.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-extractDomain',
+	examples: [
+		{ example: '"me@example.com".extractDomain()', evaluated: "'example.com'" },
+		{ example: '"http://n8n.io/workflows".extractDomain()', evaluated: "'n8n.io'" },
+		{
+			example: '"It\'s me@example.com".extractEmail().extractDomain()',
+			evaluated: "'example.com'",
+		},
+	],
 };
 
 extractUrl.doc = {
 	name: 'extractUrl',
-	description: 'Extracts a URL from a string. Returns undefined if none is found.',
+	description:
+		'Extracts the first URL found in the string. Returns <code>undefined</code> if none is found. Only recognizes full URLs, e.g. those starting with <code>http</code>.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-extractUrl',
+	examples: [{ example: '"Check out http://n8n.io".extractUrl()', evaluated: "'http://n8n.io'" }],
 };
 
 extractUrlPath.doc = {
 	name: 'extractUrlPath',
-	description: 'Extracts the path from a URL. Returns undefined if none is found.',
+	description:
+		'Returns the part of a URL after the domain, or <code>undefined</code> if no URL found. If the string also contains other content, try using <code>extractUrl()</code> first.',
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-extractUrlPath',
+	examples: [
+		{ example: '"http://n8n.io/workflows".extractUrlPath()', evaluated: "'/workflows'" },
+		{
+			example: '"Check out http://n8n.io/workflows".extractUrl().extractUrlPath()',
+			evaluated: "'/workflows'",
+		},
+	],
 };
 
 hash.doc = {
 	name: 'hash',
-	description: 'Returns a string hashed with the given algorithm. Default algorithm is `md5`.',
+	description:
+		'Returns the string hashed with the given algorithm. Defaults to md5 if not specified.',
 	section: 'edit',
 	returnType: 'string',
-	args: [{ name: 'algo?', type: 'Algorithm' }],
+	args: [
+		{
+			name: 'algo',
+			optional: true,
+			description:
+				'The hashing algorithm to use. One of <code>md5</code>, <code>base64</code>, <code>sha1</code>, <code>sha224</code>, <code>sha256</code>, <code>sha384</code>, <code>sha512</code>, <code>sha3</code>, <code>ripemd160</code>\n        ',
+			default: '"md5"',
+			type: 'string',
+		},
+	],
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-hash',
+	examples: [{ example: '"hello".hash()', evaluated: "'5d41402abc4b2a76b9719d911017c592'" }],
 };
 
 quote.doc = {
 	name: 'quote',
-	description: 'Returns a string wrapped in the quotation marks. Default quotation is `"`.',
+	description:
+		'Wraps a string in quotation marks, and escapes any quotation marks already in the string. Useful when constructing JSON, SQL, etc.',
 	section: 'edit',
 	returnType: 'string',
-	args: [{ name: 'mark?', type: 'string' }],
+	args: [
+		{
+			name: 'mark',
+			optional: true,
+			description: 'The type of quotation mark to use',
+			default: '"',
+			type: 'string',
+		},
+	],
 	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-quote',
+	examples: [{ example: '\'Nathan says "hi"\'.quote()', evaluated: '\'"Nathan says \\"hi\\""\'' }],
 };
 
 parseJson.doc = {
 	name: 'parseJson',
 	description:
-		'Parses a JSON string, constructing the JavaScript value or object described by the string.',
+		"Returns the JavaScript value or object represented by the string, or <code>undefined</code> if the string isn't valid JSON. Single-quoted JSON is not supported.",
 	section: 'cast',
 	returnType: 'any',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-parseJson',
+	examples: [
+		{ example: '\'{"name":"Nathan"}\'.parseJson()', evaluated: '\'{"name":"Nathan"}\'' },
+		{ example: "\"{'name':'Nathan'}\".parseJson()", evaluated: 'undefined' },
+		{ example: "'hello'.parseJson()", evaluated: 'undefined' },
+	],
 };
 
 base64Encode.doc = {
 	name: 'base64Encode',
-	description: 'Converts a UTF-8-encoded string to a Base64 string.',
+	description: 'Converts plain text to a base64-encoded string',
+	examples: [{ example: '"hello".base64Encode()', evaluated: '"aGVsbG8="' }],
 	section: 'edit',
 	returnType: 'string',
 	docURL:
@@ -660,17 +799,29 @@ base64Encode.doc = {
 
 base64Decode.doc = {
 	name: 'base64Decode',
-	description: 'Converts a Base64 string to a UTF-8 string.',
+	description: 'Converts a base64-encoded string to plain text',
+	examples: [{ example: '"aGVsbG8=".base64Decode()', evaluated: '"hello"' }],
 	section: 'edit',
 	returnType: 'string',
 	docURL:
 		'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-base64Decode',
 };
 
+toNumber.doc = {
+	name: 'toNumber',
+	description:
+		"Converts a string representing a number to a number. Errors if the string doesn't start with a valid number.",
+	section: 'cast',
+	returnType: 'number',
+	docURL: 'https://docs.n8n.io/code/builtin/data-transformation-functions/strings/#string-toNumber',
+	examples: [
+		{ example: '"123".toNumber()', evaluated: '123' },
+		{ example: '"1.23E10".toNumber()', evaluated: '12300000000' },
+	],
+};
+
 const toDecimalNumber: Extension = toFloat.bind({});
-toDecimalNumber.doc = { ...toFloat.doc, hidden: true };
 const toWholeNumber: Extension = toInt.bind({});
-toWholeNumber.doc = { ...toInt.doc, hidden: true };
 
 export const stringExtensions: ExtensionMap = {
 	typeName: 'String',
@@ -682,6 +833,7 @@ export const stringExtensions: ExtensionMap = {
 		toDateTime,
 		toBoolean,
 		toDecimalNumber,
+		toNumber,
 		toFloat,
 		toInt,
 		toWholeNumber,