Add formatFullname(givenName, familyName, locale)

.changeset/wet-dots-rule.md

@@ -0,0 +1,5 @@
+---
+"@labdigital/toolkit": minor
+---
+
+Add formatFullname(givenName, familyName, locale)

src/i18n.test.ts

@@ -1,4 +1,4 @@
-import { getLocalizedValue, parseLocale } from "./i18n";
+import { formatFullname, getLocalizedValue, parseLocale } from "./i18n";
 import { describe, expect, it } from "vitest";
 
 describe("getLocalizedValue", () => {
@@ -80,3 +80,23 @@ describe("parseLocale", () => {
 		expect(result.subTag).toBe(expected.subTag);
 	});
 });
+
+describe("formatFullname", () => {
+	it.each([
+		// Test cases: [givenName, familyName, locale, expectedResult]
+		["John", "Doe", "en-US", "John Doe"],
+		["John", "Doe", "ja-JP", "Doe John"],
+		["John", "Doe", "zh-CN", "Doe John"],
+		["Jean", "Dupont", "fr-FR", "Jean Dupont"],
+		["Minh", "Nguyen", "vi-VN", "Nguyen Minh"],
+		["John", "Doe", undefined, "John Doe"],
+		["John", "Doe", "fr", "John Doe"],
+		["John", "Doe", "hu-HU", "Doe John"],
+	])(
+		"should format '%s %s' correctly for locale '%s'",
+		(givenName, familyName, locale, expected) => {
+			const result = formatFullname(givenName, familyName, locale);
+			expect(result).toBe(expected);
+		},
+	);
+});

src/i18n.ts

@@ -98,3 +98,49 @@ export const parseLocale = (
 	const [languageTag, subTag] = locale.split("-");
 	return { languageTag, subTag };
 };
+
+// Locales where family name comes first
+const familyNameFirstLocales = [
+	"ja-JP", // Japan
+	"zh-CN", // Mainland China
+	"zh-TW", // Taiwan
+	"ko-KR", // Korea
+	"vi-VN", // Vietnam
+	"hu-HU", // Hungary
+	"mn-MN", // Mongolia
+];
+
+/**
+ * Formats a full name based on locale-specific conventions.
+ *
+ * Certain locales place the family name (last name) before the given name
+ * (first name), while others place the given name first. This function formats
+ * the full name accordingly.
+ *
+ * @param {string} givenName - The given (first) name of the person.
+ * @param {string} familyName - The family (last) name of the person.
+ * @param {string} locale - The locale to format the name in (e.g., 'en-US', 'ja-JP').
+ *
+ * @returns {string} The formatted full name according to the locale.
+ *
+ * @example
+ * // Returns "John Doe" for US locale
+ * formatFullname("John", "Doe", "en-US");
+ *
+ * @example
+ * // Returns "Doe John" for Japanese locale
+ * formatFullname("John", "Doe", "ja-JP");
+ */
+export const formatFullname = (
+	givenName: string,
+	familyName: string,
+	locale: string,
+): string => {
+	// Check if the locale prefers family name first
+	if (familyNameFirstLocales.includes(locale)) {
+		return `${familyName} ${givenName}`;
+	}
+
+	// For other locales, given name comes first by default
+	return `${givenName} ${familyName}`;
+};