From 519420300036bad687da2c1e61f1deef28ca5c13 Mon Sep 17 00:00:00 2001
From: kabin thakuri <kabin@dzangolab.com>
Date: Thu, 8 Jan 2026 16:07:50 +0545
Subject: [PATCH] feat(ui/CountryPicker): add autoSortOptions prop and update
 descriptions in translations

---
 .../components/FormWidgets/CountryPicker.tsx  |  59 +++--
 apps/demo/src/locales/en/ui.json              |   1 +
 apps/demo/src/locales/fr/ui.json              |   1 +
 .../src/FormWidgets/CountryPicker/index.tsx   | 207 ++++++++++++------
 4 files changed, 173 insertions(+), 95 deletions(-)

diff --git a/apps/demo/src/Views/Ui/components/FormWidgets/CountryPicker.tsx b/apps/demo/src/Views/Ui/components/FormWidgets/CountryPicker.tsx
index ef37e5c66..92110f2a4 100644
--- a/apps/demo/src/Views/Ui/components/FormWidgets/CountryPicker.tsx
+++ b/apps/demo/src/Views/Ui/components/FormWidgets/CountryPicker.tsx
@@ -19,129 +19,136 @@ export const CountryPickerDemo = () => {
   const locale = i18n.language;
 
   const data = [
+    {
+      default: "true",
+      description: t("countryPicker.propertiesDescription.autoSortOptions"),
+      id: 1,
+      prop: "autoSortOptions",
+      type: "boolean",
+    },
     {
       default: "[]",
       description: t("countryPicker.propertiesDescription.exclude"),
-      id: 1,
+      id: 2,
       prop: "exclude",
       type: "string[]",
     },
     {
       default: '"en"',
       description: t("countryPicker.propertiesDescription.fallbackLocale"),
-      id: 2,
+      id: 3,
       prop: "fallbackLocale",
       type: "string",
     },
     {
       default: "[]",
       description: t("countryPicker.propertiesDescription.favorites"),
-      id: 3,
+      id: 4,
       prop: "favorites",
       type: "string[]",
     },
     {
       default: "true",
       description: t("countryPicker.propertiesDescription.flags"),
-      id: 4,
+      id: 5,
       prop: "flags",
       type: "Boolean",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.flagsPath"),
-      id: 5,
+      id: 6,
       prop: "flagsPath",
       type: "(code: string) => string",
     },
     {
       default: "left",
       description: t("countryPicker.propertiesDescription.flagsPosition"),
-      id: 6,
+      id: 7,
       prop: "flagsPosition",
       type: "left | right | right-edge",
     },
     {
       default: "rectangular",
       description: t("countryPicker.propertiesDescription.flagsStyle"),
-      id: 7,
+      id: 8,
       prop: "flagsStyle",
       type: "circle | rectangular | square",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.groups"),
-      id: 8,
+      id: 9,
       prop: "groups",
       type: "GroupData",
     },
     {
       default: "[]",
       description: t("countryPicker.propertiesDescription.include"),
-      id: 9,
+      id: 10,
       prop: "include",
       type: "string[]",
     },
     {
       default: "true",
       description: t("countryPicker.propertiesDescription.includeFavorites"),
-      id: 10,
+      id: 11,
       prop: "includeFavorites",
       type: "boolean",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.label"),
-      id: 11,
+      id: 12,
       prop: "label",
       type: "string",
     },
     {
       default: '"en"',
       description: t("countryPicker.propertiesDescription.locale"),
-      id: 12,
+      id: 13,
       prop: "locale",
       type: "string",
     },
     {
       default: "{ en: defaultEnCatalogue }",
       description: t("countryPicker.propertiesDescription.i18n"),
-      id: 13,
+      id: 14,
       prop: "locales",
       type: "Record<string, Record<string, string>>",
     },
     {
       default: "false",
       description: t("countryPicker.propertiesDescription.multiple"),
-      id: 14,
+      id: 15,
       prop: "multiple",
       type: "boolean",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.name"),
-      id: 15,
+      id: 16,
       prop: "name",
       type: "string",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.onChange"),
-      id: 16,
+      id: 17,
       prop: "onChange",
       type: "(value: string | string[]) => void",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.placeholder"),
-      id: 17,
+      id: 18,
       prop: "placeholder",
       type: "string",
     },
     {
       default: "-",
       description: t("countryPicker.propertiesDescription.value"),
-      id: 18,
+      id: 19,
       prop: "value",
       type: "string | string[]",
     },
@@ -410,7 +417,6 @@ const selectedLocale = i18n.language;
 
       <Section title={t("countryPicker.favorites")}>
         <CountryPicker
-          autoSortOptions={false}
           favorites={["NP", "US", "GB"]}
           label={t("countryPicker.labels.single")}
           locale={locale}
@@ -425,7 +431,6 @@ const [singleSelectValue, setSingleSelectValue] = useState<string>("");
 const selectedLocale = i18n.language;
 
 <CountryPicker
-  autoSortOptions={false}
   favorites={["NP", "US", "GB"]} 
   label={t("countryPicker.labels.single")}
   locale={selectedLocale}
@@ -437,7 +442,6 @@ const selectedLocale = i18n.language;
 
       <Section title={t("countryPicker.includeFavorites")}>
         <CountryPicker
-          autoSortOptions={false}
           favorites={["NP", "US", "GB"]}
           includeFavorites={false}
           label={t("countryPicker.labels.single")}
@@ -453,7 +457,6 @@ const [singleSelectValue, setSingleSelectValue] = useState<string>("");
 const selectedLocale = i18n.language;
 
 <CountryPicker
-  autoSortOptions={false}
   favorites={["NP", "US", "GB"]} 
   includeFavorites={false}
   label={t("countryPicker.labels.single")}
@@ -466,7 +469,6 @@ const selectedLocale = i18n.language;
 
       <Section title={t("countryPicker.groupingDefault")}>
         <CountryPicker
-          autoSortOptions={false}
           groups={{
             "European Union": defaultGroups?.EU || [],
             ASEAN: defaultGroups?.ASEAN || [],
@@ -485,7 +487,6 @@ const selectedLocale = i18n.language;
 import { CountryPicker, defaultGroups } from "@prefabs.tech/react-ui";
 
 <CountryPicker
-  autoSortOptions={false}
   groups={{
     "European Union": defaultGroups.EU,
     "ASEAN": defaultGroups.ASEAN
@@ -502,7 +503,6 @@ import { CountryPicker, defaultGroups } from "@prefabs.tech/react-ui";
 
       <Section title={t("countryPicker.groupingCustom")}>
         <CountryPicker
-          autoSortOptions={false}
           groups={{
             "North America HQ": ["US", "CA"],
             "Offshore Dev Center": ["IN", "VN", "PH"],
@@ -526,7 +526,6 @@ const myRegions = {
 };
 
 <CountryPicker
-  autoSortOptions={false}
   groups={myRegions}
   label={t("countryPicker.labels.single")}
   locale={locale}
@@ -541,10 +540,10 @@ const myRegions = {
       <Section title={t("countryPicker.groupingFavorites")}>
         <CountryPicker
           autoSortOptions={false}
-          favorites={["FR", "US"]}
+          favorites={["US", "FR"]}
           groups={{
-            Europe: ["FR", "DE", "IT", "ES"],
             "North America": ["US", "CA"],
+            Europe: ["FR", "DE", "IT", "ES"],
           }}
           label={t("countryPicker.labels.single")}
           locale={locale}
@@ -559,10 +558,10 @@ const myRegions = {
           exampleCode='
 <CountryPicker
   autoSortOptions={false}
-  favorites={["FR", "US"]}
+  favorites={["US", "FR"]}
   groups={{
+    "North America": ["US", "CA"],
     "Europe": ["FR", "DE", "IT", "ES"],
-    "North America": ["US", "CA"]
   }}
   label={t("countryPicker.labels.single")}
   locale={locale}
diff --git a/apps/demo/src/locales/en/ui.json b/apps/demo/src/locales/en/ui.json
index 925ad50e5..a9d406e24 100644
--- a/apps/demo/src/locales/en/ui.json
+++ b/apps/demo/src/locales/en/ui.json
@@ -147,6 +147,7 @@
       "single": "Select a country..."
     },
     "propertiesDescription": {
+      "autoSortOptions":"By default, options are sorted alphabetically. If false, countries are sorted by priority in the order groups → favorites → include → fallback-locale translations, preserving the defined order.",
       "data": "Custom country data to overwrite existing entries or add new ones.",
       "exclude": "An array of country codes to remove from the list.",
       "fallbackLocale": "Locale used when active locale translation is missing.",
diff --git a/apps/demo/src/locales/fr/ui.json b/apps/demo/src/locales/fr/ui.json
index 9a8f1ab24..4e92a5aba 100644
--- a/apps/demo/src/locales/fr/ui.json
+++ b/apps/demo/src/locales/fr/ui.json
@@ -147,6 +147,7 @@
       "single": "Select a country... (fr)"
     },
     "propertiesDescription": {
+      "autoSortOptions":"By default, options are sorted alphabetically. If false, countries are sorted by priority in the order groups → favorites → include → fallback-locale translations, preserving the defined order. (fr)",
       "data": "Custom country data to overwrite existing entries or add new ones. (fr)",
       "exclude": "An array of country codes to remove from the list. (fr)",
       "fallbackLocale": "Locale used when active locale translation is missing. (fr)",
diff --git a/packages/ui/src/FormWidgets/CountryPicker/index.tsx b/packages/ui/src/FormWidgets/CountryPicker/index.tsx
index 7fd01c325..266a4085c 100644
--- a/packages/ui/src/FormWidgets/CountryPicker/index.tsx
+++ b/packages/ui/src/FormWidgets/CountryPicker/index.tsx
@@ -4,7 +4,7 @@ import { getFallbackTranslation } from "../../utils/CountryPicker";
 import { Select, ISelectProperties } from "../Select";
 import defaultGroups from "./groups.json";
 
-import type { Option } from "../Select";
+import type { Option, GroupedOption } from "../Select";
 
 export type Translation = Record<string, string>;
 export type Locales = Record<string, Translation>;
@@ -19,6 +19,7 @@ export type CountryPickerProperties<T> = Omit<
   ISelectProperties<T>,
   "options"
 > & {
+  autoSortOptions?: boolean;
   exclude?: string[];
   fallbackLocale?: string;
   favorites?: string[];
@@ -51,22 +52,48 @@ const getBaseOptions = <T,>(
 
   const baseOptions: Option<T>[] = [];
 
-  Object.entries(fallbackData).forEach(([code, fallbackLabel]) => {
-    if (exclude && exclude.includes(code)) {
-      return;
-    }
+  if (include?.length) {
+    include.forEach((code) => {
+      if (exclude?.includes(code)) {
+        return;
+      }
 
-    if (include && !include.includes(code)) {
+      if (!fallbackData[code]) {
+        return;
+      }
+
+      baseOptions.push({
+        value: code as unknown as T,
+        label: getLabel(code, locale, locales, fallbackData[code]),
+      });
+    });
+
+    return baseOptions;
+  }
+
+  Object.entries(fallbackData).forEach(([code, fallbackLabel]) => {
+    if (exclude?.includes(code)) {
       return;
     }
 
-    const label = locales?.[locale]?.[code] || fallbackLabel || code;
-    baseOptions.push({ value: code as unknown as T, label });
+    baseOptions.push({
+      value: code as unknown as T,
+      label: getLabel(code, locale, locales, fallbackData[code]),
+    });
   });
 
   return baseOptions;
 };
 
+const getFavoriteOptions = <T,>(
+  baseOptions: Option<T>[],
+  favorites: string[],
+) => {
+  return favorites
+    .map((code) => baseOptions.find((option) => String(option.value) === code))
+    .filter(Boolean) as Option<T>[];
+};
+
 const getFlagClass = (
   code: string | undefined,
   position: string,
@@ -86,55 +113,46 @@ const getFlagClass = (
 const getGroups = <T,>(
   groups: Groups,
   list: Option<T>[],
-): { label: string; options: Option<T>[] }[] => {
-  const groupedResult: { label: string; options: Option<T>[] }[] = [];
+): GroupedOption<T>[] => {
+  const optionMap = new Map(
+    list.map((option) => [String(option.value), option]),
+  );
 
-  Object.entries(groups).forEach(([groupLabel, groupCodes]) => {
-    const groupOptions = list.filter((option) =>
-      groupCodes.includes(String(option.value)),
-    );
+  return Object.entries(groups).reduce<GroupedOption<T>[]>(
+    (groupedOptions, [groupLabel, groupCodes]) => {
+      const options = groupCodes
+        .map((code) => optionMap.get(code))
+        .filter(Boolean) as Option<T>[];
 
-    if (groupOptions.length > 0) {
-      groupedResult.push({
-        label: groupLabel,
-        options: groupOptions,
-      });
-    }
-  });
+      if (options.length) {
+        groupedOptions.push({ label: groupLabel, options });
+      }
 
-  return groupedResult;
+      return groupedOptions;
+    },
+    [],
+  );
+};
+
+const getLabel = (
+  code: string,
+  locale: string,
+  locales: Locales | undefined,
+  fallbackLabel?: string,
+) => {
+  return locales?.[locale]?.[code] || fallbackLabel || code;
 };
 
 const getOptions = <T,>({
-  exclude,
-  fallbackLocale = "en",
+  baseOptions,
   favorites,
   groups,
-  include,
   includeFavorites = true,
   labels,
-  locale = "en",
-  locales,
 }: Pick<
   CountryPickerProperties<T>,
-  | "exclude"
-  | "fallbackLocale"
-  | "favorites"
-  | "groups"
-  | "include"
-  | "includeFavorites"
-  | "labels"
-  | "locale"
-  | "locales"
->) => {
-  const baseOptions = getBaseOptions<T>(
-    exclude,
-    fallbackLocale,
-    include,
-    locale,
-    locales,
-  );
-
+  "favorites" | "groups" | "includeFavorites" | "labels"
+> & { baseOptions: Option<T>[] }) => {
   if (favorites && favorites.length > 0) {
     return getOptionsWithFavorites(
       baseOptions,
@@ -159,9 +177,7 @@ const getOptionsWithFavorites = <T,>(
   groups?: Groups,
   labels?: CountryPickerLabels,
 ) => {
-  const favoriteOptions = baseOptions.filter((option) =>
-    favorites.includes(String(option.value)),
-  );
+  const favoriteOptions = getFavoriteOptions(baseOptions, favorites);
 
   const mainOptions = includeFavorites
     ? baseOptions
@@ -186,6 +202,32 @@ const getOptionsWithFavorites = <T,>(
   ];
 };
 
+const getSortedOptions = <T,>(
+  isOptionsGrouped: boolean,
+  hasFavoriteOptions: boolean,
+  options: Option<T>[] | GroupedOption<T>[],
+) => {
+  if (!isOptionsGrouped) {
+    return [...(options as Option<T>[])].sort(sortByLabel);
+  }
+
+  const sortedOptionsGroup = (options as GroupedOption<T>[]).map((group) => {
+    return {
+      ...group,
+      options: [...(group.options as Option<T>[])].sort(sortByLabel),
+    };
+  });
+
+  if (hasFavoriteOptions) {
+    return [
+      sortedOptionsGroup[0],
+      ...sortedOptionsGroup.slice(1).sort(sortByLabel),
+    ];
+  }
+
+  return sortedOptionsGroup.sort(sortByLabel);
+};
+
 const renderCountryOption = <T,>(
   option: Option<T>,
   {
@@ -214,7 +256,23 @@ const renderCountryOption = <T,>(
   );
 };
 
+const sortByLabel = <T,>(
+  optionA: Option<T> | GroupedOption<T>,
+  optionB: Option<T> | GroupedOption<T>,
+) => {
+  if (!optionA.label) {
+    return 1;
+  }
+
+  if (!optionB.label) {
+    return -1;
+  }
+
+  return optionA.label.localeCompare(optionB.label);
+};
+
 export const CountryPicker = <T extends string | number>({
+  autoSortOptions = true,
   exclude,
   fallbackLocale = "en",
   favorites,
@@ -230,29 +288,47 @@ export const CountryPicker = <T extends string | number>({
   locale = "en",
   ...properties
 }: CountryPickerProperties<T>) => {
-  const options = useMemo(() => {
-    return getOptions<T>({
+  const baseOptions = useMemo(() => {
+    return getBaseOptions<T>(
       exclude,
       fallbackLocale,
+      include,
+      locale,
+      locales,
+    ) as Option<T>[];
+  }, [exclude, fallbackLocale, include, locale, locales]);
+
+  const options = useMemo(() => {
+    return getOptions<T>({
+      baseOptions,
       favorites,
       groups,
-      include,
       includeFavorites,
       labels,
-      locale,
-      locales,
     });
-  }, [
-    exclude,
-    fallbackLocale,
-    favorites,
-    groups,
-    include,
-    includeFavorites,
-    labels,
-    locale,
-    locales,
-  ]);
+  }, [baseOptions, favorites, groups, includeFavorites, labels]);
+
+  const favoriteOptions = useMemo(() => {
+    return favorites?.length ? getFavoriteOptions(baseOptions, favorites) : [];
+  }, [baseOptions, favorites]);
+
+  const isOptionsGrouped = useMemo(() => {
+    return (
+      Array.isArray(options) && options.length > 0 && "options" in options[0]
+    );
+  }, [options]);
+
+  const sortedOptions = useMemo<Option<T>[] | GroupedOption<T>[]>(() => {
+    if (!autoSortOptions) {
+      return options as Option<T>[] | GroupedOption<T>[];
+    }
+
+    return getSortedOptions(
+      isOptionsGrouped,
+      !!favoriteOptions.length,
+      options,
+    );
+  }, [autoSortOptions, favoriteOptions, isOptionsGrouped, options]);
 
   const handleOnChange = useCallback(
     (value: T | T[]) => {
@@ -282,7 +358,8 @@ export const CountryPicker = <T extends string | number>({
   return (
     <Select
       {...(properties as ISelectProperties<T>)}
-      options={options}
+      autoSortOptions={false}
+      options={sortedOptions}
       renderOption={properties.renderOption ?? handleRenderOption}
       onChange={handleOnChange}
     />