@vtex/faststore-plugin-buyer-portal 2.0.13 → 2.0.14

package/src/features/shared/localization/constants.ts

@@ -0,0 +1,31 @@
+/**
+ * Maps each buyer portal feature to its CMS localization entry UUID.
+ * These UUIDs identify the localization entries in the Content Platform API
+ * (see LOCALIZATION_BASE_URL) and are used to fetch localized strings per feature at runtime.
+ */
+export const LOCALIZATION_ENTRY_IDS = {
+  addresses: "29747c90-344b-45db-9ef0-192b537b12e7",
+  budgets: "54f982e2-a823-40c6-954d-f35945413bde",
+  users: "7cba4de2-c752-4ee6-96c1-a7cbd6a39b19",
+  shared: "4785424c-3eb7-4ab7-b13e-78a1029c8f4d",
+  accountingFields: "588dab31-0afe-437e-9f3b-63c76ff7552b",
+  buyingPolicies: "e3603de6-d427-44de-aba0-e77d597b9f22",
+  creditCards: "cccdd4dc-f73d-4b43-85a3-3e1a2bbc8b1c",
+  orgUnits: "2bf471ed-736d-40b7-8162-139ce9ed5a99",
+  paymentMethods: "7a8cde2e-3fac-4f30-b264-e135d0ded2d7",
+  productAssortment: "cd636c6c-37cf-4078-bc83-378e55751718",
+  profile: "57c0716a-12bf-460c-aa57-1679bf48c043",
+  contracts: "81d0f596-15f5-4fa8-a6a7-f3e5040e6eb9",
+  roles: "13ce6df5-7fdc-4b4b-be9d-f8c4f0a0a488",
+  b2bAgent: "dc4fcf7d-00a6-4c9f-ac26-94833288cc46",
+  orderEntry: "3cd8c183-129f-4622-ac48-0db54154ecf8",
+} as const;
+
+export type LocalizationFeature = keyof typeof LOCALIZATION_ENTRY_IDS;
+export type LocalizationEntryId =
+  (typeof LOCALIZATION_ENTRY_IDS)[LocalizationFeature];
+
+/** Content type slug in the Content Platform API path (see cms_content_type__i18n.jsonc). */
+export const LOCALIZATION_CONTENT_TYPE = "b2bLocalization";
+
+export const LOCALIZATION_BASE_URL = `https://vtex.vtexcommercestable.com.br/api/content-platform/data/vtex/b2b/${LOCALIZATION_CONTENT_TYPE}`;

package/src/features/shared/localization/createLocalize.ts

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+
+import type { LabelMap, LocalizeFn } from "./types";
+
+const PLACEHOLDER_PATTERN = /\{(\d+)\}/g;
+
+/**
+ * Returns true when the interpolations array contains at least one value that is
+ * not a plain string or number — i.e. a React node (element, fragment, etc.).
+ */
+const hasReactNodes = (
+  interpolations: (string | number | ReactNode)[]
+): boolean =>
+  interpolations.some(
+    (v) =>
+      v !== null &&
+      v !== undefined &&
+      typeof v !== "string" &&
+      typeof v !== "number"
+  );
+
+/**
+ * Builds an array of alternating text segments and React nodes by walking the
+ * template string with exec() rather than replace(), so non-string values can
+ * be inserted at placeholder positions without stringification.
+ */
+const interpolateNodes = (
+  template: string,
+  interpolations: ReactNode[]
+): ReactNode[] => {
+  const result: ReactNode[] = [];
+  const regex = new RegExp(PLACEHOLDER_PATTERN.source, "g");
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(template)) !== null) {
+    if (match.index > lastIndex) {
+      result.push(template.slice(lastIndex, match.index));
+    }
+    const idx = Number(match[1]);
+    const value = interpolations[idx];
+    result.push(value !== undefined ? value : match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < template.length) {
+    result.push(template.slice(lastIndex));
+  }
+
+  return result;
+};
+
+export const createLocalize = (labels: LabelMap): LocalizeFn => {
+  function t(key: string, interpolations?: (string | number)[]): string;
+  function t(key: string, interpolations: ReactNode[]): ReactNode;
+  function t(
+    key: string,
+    interpolations?: (string | number | ReactNode)[]
+  ): string | ReactNode {
+    const template = labels[key];
+
+    if (template === undefined) return key;
+
+    if (!interpolations || interpolations.length === 0) return template;
+
+    if (hasReactNodes(interpolations)) {
+      return interpolateNodes(template, interpolations as ReactNode[]);
+    }
+
+    // Pure string/number path — O(1) replace, same as before.
+    return template.replace(PLACEHOLDER_PATTERN, (token, index: string) => {
+      const value = (interpolations as (string | number)[])[Number(index)];
+      return value === undefined ? token : String(value);
+    });
+  }
+
+  return t as LocalizeFn;
+};

package/src/features/shared/localization/services/get-localization-labels.service.ts

@@ -0,0 +1,76 @@
+import { logError } from "../../services/logger";
+import { localizationClient } from "../clients/LocalizationClient";
+import { LOCALIZATION_ENTRY_IDS, type LocalizationEntryId } from "../constants";
+
+import type {
+  LocalizationLabelType,
+  LabelMap,
+  GetLocalizationLabelsParams,
+} from "../types";
+
+// Permanent process-local cache + single-flight, keyed by (entryId, locale).
+const resolved = new Map<string, LabelMap>();
+const inFlight = new Map<string, Promise<LabelMap>>();
+
+const toLabelMap = (labels: LocalizationLabelType[]): LabelMap =>
+  labels.reduce<LabelMap>((acc, { key, value }) => {
+    acc[key] = value;
+    return acc;
+  }, {});
+
+// Fetches (and permanently caches) a single entry.
+// Logs an error and falls back to {} on failure — never throws.
+const fetchEntry = (entryId: string, locale: string): Promise<LabelMap> => {
+  const cacheKey = `${entryId}::${locale}`;
+
+  const cached = resolved.get(cacheKey);
+  if (cached) return Promise.resolve(cached);
+
+  const ongoing = inFlight.get(cacheKey);
+  if (ongoing) return ongoing;
+
+  const promise = localizationClient
+    .getEntry(entryId, locale)
+    .then((data) => {
+      const map = toLabelMap(data?.labels ?? []);
+      resolved.set(cacheKey, map); // permanent cache (no TTL)
+      return map;
+    })
+    .catch((error: unknown) => {
+      logError("Failed to fetch localization labels", {
+        entryId,
+        locale,
+        error_message: error instanceof Error ? error.message : String(error),
+      });
+      return {} as LabelMap; // do NOT write to `resolved`; allow retry on next request
+    })
+    .finally(() => {
+      inFlight.delete(cacheKey);
+    });
+
+  inFlight.set(cacheKey, promise);
+  return promise;
+};
+
+/** Clears the process-local cache. Intended for use in tests only. */
+export const _resetLocalizationCache = () => {
+  resolved.clear();
+  inFlight.clear();
+};
+
+export const getLocalizationLabelsService = async ({
+  entryIds,
+  locale = "",
+}: GetLocalizationLabelsParams): Promise<LabelMap> => {
+  const requested = Array.isArray(entryIds) ? entryIds : [entryIds];
+
+  // Always include `shared`; de-duplicate via Set.
+  const ids = Array.from(
+    new Set<LocalizationEntryId>([LOCALIZATION_ENTRY_IDS.shared, ...requested])
+  );
+
+  const maps = await Promise.all(ids.map((id) => fetchEntry(id, locale)));
+
+  // Namespaced keys make this merge collision-safe.
+  return Object.assign({}, ...maps) as LabelMap;
+};

package/src/features/shared/localization/types.ts

@@ -0,0 +1,66 @@
+export type LocalizationLanguageType = {
+  name: string;
+  language_code: string;
+  native_name: string;
+  script: string;
+  text_direction: "ltr" | "rtl" | string;
+  utf_encoding: string;
+};
+
+export type LocalizationRegionType = {
+  name: string;
+  flag: string;
+  country_code: string;
+  continent: string;
+  date_format: string;
+  time_format: "12h" | "24h" | string;
+  time_format_mask: string;
+  unit_system: "imperial" | "metric" | string;
+  default_timezone: string;
+};
+
+export type LocalizationLocaleMetadataType = {
+  code: string;
+  locale: string;
+  language: LocalizationLanguageType;
+  region: LocalizationRegionType;
+};
+
+export type LocalizationLabelType = {
+  key: string;
+  value: string;
+};
+
+export type LocalizationLocaleDataType = {
+  locale_metadata: LocalizationLocaleMetadataType; // typed, not consumed yet
+  labels: LocalizationLabelType[];
+};
+
+import type { ReactNode } from "react";
+
+import type { LocalizationEntryId } from "./constants";
+
+/** Flat, O(1)-lookup label map produced by the service. */
+export type LabelMap = Record<string, string>;
+
+/** Parameters accepted by `getLocalizationLabelsService`. */
+export type GetLocalizationLabelsParams = {
+  entryIds: LocalizationEntryId | LocalizationEntryId[];
+  locale?: string;
+};
+
+/**
+ * Translation function exposed to components.
+ *
+ * Two call signatures:
+ *  - `t(key, (string | number)[])` → `string`   – pure text interpolation (O(1) replace)
+ *  - `t(key, ReactNode[])`          → `ReactNode` – node interpolation; returns an array of
+ *    alternating text segments and the supplied React nodes, ready to spread inside JSX.
+ *
+ * The second overload is selected automatically by TypeScript whenever at least one
+ * interpolation value is not a `string` or `number` (e.g. a JSX element).
+ */
+export type LocalizeFn = {
+  (key: string, interpolations?: (string | number)[]): string;
+  (key: string, interpolations: ReactNode[]): ReactNode;
+};

package/src/features/shared/localization/withLocalization.tsx

@@ -0,0 +1,22 @@
+import { type ComponentType } from "react";
+
+import { LocalizationProvider } from "./LocalizationContext";
+
+import type { LabelMap } from "./types";
+
+export const withLocalization = <T extends Record<string, unknown>>(
+  Component: ComponentType<T>
+) =>
+  function WrappedWithLocalization(
+    props: T & { context: { localization?: { labels: LabelMap } } }
+  ) {
+    const labels = props.context?.localization?.labels ?? {};
+    return (
+      <LocalizationProvider labels={labels}>
+        {/* Forward ALL props (including `context`) so `withBuyerPortal` downstream
+            still receives it. `withLocalization` must sit BEFORE `withBuyerPortal`,
+            which strips `context` (see Decision 1 in specs/custom-localization-system.md). */}
+        <Component {...props} />
+      </LocalizationProvider>
+    );
+  };

package/src/features/shared/types/AuthRouteProps.ts

@@ -1,6 +1,8 @@
 import { ErrorBoundaryProps } from "../components/ErrorBoundary/types";
 import { ClientContext } from "../utils";
 
+import type { LabelMap } from "../localization/types";
+
 export type AuthRouteProps<T> =
   | {
       authorized: true;
@@ -15,4 +17,7 @@ export type AuthRouteProps<T> =
       error?: ErrorBoundaryProps;
       data?: T;
       clientContext?: ClientContext;
+      context?: {
+        localization?: { labels: LabelMap };
+      };
     };

package/src/features/shared/types/LoaderData.ts

@@ -7,4 +7,5 @@ export type LoaderData<QueryType = any> = {
     writeHead: (status: number, headers: Record<string, string>) => void;
     end: () => void;
   };
+  locale?: string;
 } & (QueryType extends undefined ? { query?: never } : { query: QueryType });

package/src/features/shared/utils/addresLabelToPropMapping.ts

@@ -1,12 +1,12 @@
 export const addressLabelToPropMapping = {
-  name: "Address Name",
-  streetAddress: "Street address",
-  streetNumber: "Number",
-  streetAddress2: "Apt, Suite, Building",
-  country: "Country",
-  zip: "Postal Code",
-  state: "State",
-  city: "City",
-  geoCoordinates: "Geo coordinate",
-  types: "Address Type",
+  name: "shared.labels.addressName",
+  streetAddress: "shared.labels.streetAddress",
+  streetNumber: "shared.labels.streetNumber",
+  streetAddress2: "shared.labels.streetAddress2",
+  country: "shared.labels.country",
+  zip: "shared.labels.postalCode",
+  state: "shared.labels.state",
+  city: "shared.labels.city",
+  geoCoordinates: "shared.labels.geoCoordinate",
+  types: "shared.labels.addressType",
 };

package/src/features/shared/utils/constants.ts

@@ -22,7 +22,4 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "2.0.13";
-
-export const CHANGES_TIMEOUT_MESSAGE =
-  "Changes may take up to 10 minutes to apply.";
+export const CURRENT_VERSION = "2.0.14";

package/src/features/shared/utils/getContractSettingsLinks.ts

@@ -1,30 +1,35 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
 
-export const getContractSettingsLinks = ({
-  orgUnitId,
-  contractId,
-}: {
-  orgUnitId: string;
-  contractId: string;
-}) => [
+import type { LocalizeFn } from "../localization/types";
+
+export const getContractSettingsLinks = (
+  {
+    orgUnitId,
+    contractId,
+  }: {
+    orgUnitId: string;
+    contractId: string;
+  },
+  t: LocalizeFn
+) => [
   {
-    name: "Profile",
+    name: t("layouts.navigation.profile"),
     link: buyerPortalRoutes.profileDetails({ orgUnitId, contractId }),
   },
   {
-    name: "Addresses",
+    name: t("layouts.navigation.addresses"),
     link: buyerPortalRoutes.addresses({ orgUnitId, contractId }),
   },
   {
-    name: "Payment methods",
+    name: t("layouts.navigation.paymentMethods"),
     link: buyerPortalRoutes.paymentMethods({ orgUnitId, contractId }),
   },
   {
-    name: "Credit cards",
+    name: t("layouts.navigation.creditCards"),
     link: buyerPortalRoutes.creditCards({ orgUnitId, contractId }),
   },
   {
-    name: "Assortments",
+    name: t("layouts.navigation.assortments"),
     link: buyerPortalRoutes.productAssortment({ orgUnitId, contractId }),
   },
 ];

package/src/features/shared/utils/getFinanceSettingsLinks.ts

@@ -1,18 +1,23 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
 
-export const getFinanceSettingsLinks = ({
-  orgUnitId,
-  contractId,
-}: {
-  orgUnitId: string;
-  contractId: string;
-}) => [
+import type { LocalizeFn } from "../localization/types";
+
+export const getFinanceSettingsLinks = (
+  {
+    orgUnitId,
+    contractId,
+  }: {
+    orgUnitId: string;
+    contractId: string;
+  },
+  t: LocalizeFn
+) => [
   {
-    name: "Budgets",
+    name: t("layouts.navigation.budgets"),
     link: buyerPortalRoutes.budgets({ orgUnitId, contractId }),
   },
   {
-    name: "Buying Policies",
+    name: t("layouts.navigation.buyingPolicies"),
     link: buyerPortalRoutes.buyingPolicies({ orgUnitId, contractId }),
   },
 ];

package/src/features/shared/utils/getKeyByValue.ts

@@ -5,6 +5,6 @@ export const getKeyByValue = (object: Dictionary<string>, value: string) => {
 };
 
 export const sortingOptions: Dictionary<string> = {
-  Users: "users",
-  "Shipping Addresses": "addresses",
+  "shared.labels.users": "users",
+  "shared.labels.shippingAddresses": "addresses",
 };

package/src/features/shared/utils/getOrganizationSettingsLinks.ts

@@ -1,16 +1,26 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
 
+import type { LocalizeFn } from "../localization/types";
+
 export const getOrganizationSettingsLinks = ({
   orgUnitId,
   contractId,
+  t,
 }: {
   orgUnitId: string;
   contractId?: string;
+  t: LocalizeFn;
 }) => [
-  { name: "Users", link: buyerPortalRoutes.users({ orgUnitId, contractId }) },
-  { name: "Roles", link: buyerPortalRoutes.roles({ orgUnitId, contractId }) },
   {
-    name: "Organizational Units",
+    name: t("layouts.navigation.users"),
+    link: buyerPortalRoutes.users({ orgUnitId, contractId }),
+  },
+  {
+    name: t("layouts.navigation.roles"),
+    link: buyerPortalRoutes.roles({ orgUnitId, contractId }),
+  },
+  {
+    name: t("layouts.navigation.organizationalUnits"),
     link: buyerPortalRoutes.orgUnits({ orgUnitId, contractId }),
   },
 ];

package/src/features/shared/utils/getSumaListingSidebarLinks.ts

@@ -2,17 +2,22 @@ import { buyerPortalRoutes } from "./buyerPortalRoutes";
 import { getFinanceSettingsLinks } from "./getFinanceSettingsLinks";
 import { getOrganizationSettingsLinks } from "./getOrganizationSettingsLinks";
 
-export const getSumaListingSidebarLinks = ({
-  orgUnitId,
-  contractId,
-}: {
-  orgUnitId: string;
-  contractId: string;
-}) => [
+import type { LocalizeFn } from "../localization/types";
+
+export const getSumaListingSidebarLinks = (
+  {
+    orgUnitId,
+    contractId,
+  }: {
+    orgUnitId: string;
+    contractId: string;
+  },
+  t: LocalizeFn
+) => [
   {
-    name: "Contracts",
+    name: t("layouts.navigation.contracts"),
     link: buyerPortalRoutes.contracts({ orgUnitId }),
   },
-  ...getOrganizationSettingsLinks({ orgUnitId, contractId }),
-  ...getFinanceSettingsLinks({ orgUnitId, contractId }),
+  ...getOrganizationSettingsLinks({ orgUnitId, t }),
+  ...getFinanceSettingsLinks({ orgUnitId, contractId }, t),
 ];

package/src/features/shared/utils/index.ts

@@ -32,7 +32,9 @@ export { roles, type Role } from "./roles";
 export {
   sortAscending,
   sortDescending,
+  sortingOptionI18nKeys,
   sortingOptions,
+  statusFilterI18nKeys,
   statusFilters,
   updateSort,
   userTypesFilters,

package/src/features/shared/utils/routeLayoutMapping.ts

@@ -14,81 +14,81 @@ export const ROUTE_TABS_LAYOUT_MAPPING: Record<string, RouteTabsLayoutConfig> =
   {
     "/pvt/organization-account/profile/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Profile",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.profile",
     },
     "/pvt/organization-account/addresses/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Addresses",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.addresses",
     },
     "/pvt/organization-account/address/[orgUnitId]/[contractId]/[addressId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Address Details",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.addressDetails",
     },
     "/pvt/organization-account/payment-groups/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Payment Methods",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.paymentMethods",
     },
     "/pvt/organization-account/credit-cards/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Credit Cards",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.creditCards",
     },
     "/pvt/organization-account/product-assortment/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
-      pageName: "Contract",
-      pageTitle: "Assortments",
+      pageName: "layouts.tabs.contract",
+      pageTitle: "layouts.titles.assortments",
     },
     "/pvt/organization-account/accounting-field/[orgUnitId]/[contractId]/[accountingFieldId]":
       {
         layout: "ContractTabsLayout",
-        pageName: "Contract",
-        pageTitle: "Accounting field",
+        pageName: "layouts.tabs.contract",
+        pageTitle: "layouts.titles.accountingField",
       },
     "/pvt/organization-account/buying-policies/[orgUnitId]/[contractId]": {
       layout: "FinanceTabsLayout",
-      pageName: "Finance and Compliance",
-      pageTitle: "Buying Policies",
+      pageName: "layouts.tabs.financeAndCompliance",
+      pageTitle: "layouts.titles.buyingPolicies",
     },
     "/pvt/organization-account/buying-policy/[orgUnitId]/[contractId]/[buyingPolicyId]":
       {
         layout: "FinanceTabsLayout",
-        pageName: "Finance and Compliance",
-        pageTitle: "Buying Policy Details",
+        pageName: "layouts.tabs.financeAndCompliance",
+        pageTitle: "layouts.titles.buyingPolicyDetails",
       },
 
     "/pvt/organization-account/roles/[orgUnitId]": {
       layout: "OrgUnitTabsLayout",
-      pageName: "Organization",
-      pageTitle: "Roles",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.roles",
     },
     "/pvt/organization-account/roles/[orgUnitId]/[roleName]": {
       layout: "OrgUnitTabsLayout",
-      pageName: "Organization",
-      pageTitle: "Role Details",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.roleDetails",
     },
     "/pvt/organization-account/users/[orgUnitId]": {
       layout: "OrgUnitTabsLayout",
-      pageName: "Organization",
-      pageTitle: "Users",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.users",
     },
     "/pvt/organization-account/user/[orgUnitId]/[userId]": {
       layout: "OrgUnitTabsLayout",
-      pageName: "Organization",
-      pageTitle: "User Details",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.userDetails",
     },
     "/pvt/organization-account/org-units/[orgUnitId]": {
       layout: "OrgUnitTabsLayout",
-      pageName: "Organization",
-      pageTitle: "Organization Details",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.organizationDetails",
     },
     "/pvt/organization-account/org-unit/[orgUnitId]": {
       layout: "OrgUnitDetailsLayout",
-      pageName: "Organization",
-      pageTitle: "Organization Details",
+      pageName: "layouts.tabs.organization",
+      pageTitle: "layouts.titles.organizationDetails",
     },
   };
 

package/src/features/shared/utils/search.tsx

@@ -8,6 +8,11 @@ export const statusFilters: Dictionary<boolean> = {
   Inativo: false,
 };
 
+export const statusFilterI18nKeys: Dictionary<string> = {
+  Ativo: "shared.labels.active",
+  Inativo: "shared.labels.inactive",
+};
+
 export const userTypesFilters = ["Admin", "Buyer"];
 
 export const sortingOptions: Dictionary<string> = {
@@ -15,6 +20,11 @@ export const sortingOptions: Dictionary<string> = {
   "Alphabetical Order Desc": "name",
 };
 
+export const sortingOptionI18nKeys: Dictionary<string> = {
+  "Alphabetical Order": "shared.labels.alphabeticalOrder",
+  "Alphabetical Order Desc": "shared.labels.alphabeticalOrderDesc",
+};
+
 export const updateSort = (arrayToSort: any[], selectedOption: string) => {
   switch (selectedOption) {
     case "Alphabetical Order": {

package/src/features/shared/utils/withAuth.tsx

@@ -31,10 +31,16 @@ export const withAuth = <T extends Record<string, unknown>>(
       return null;
     }
 
+    // In the error case props.data is undefined; forward props.context so withLocalization
+    // can read localization labels. In the success case context comes from props.data spread.
+    const errorContext =
+      !props?.authorized && "context" in props ? props.context : undefined;
+
     // If authorized, render the component with the data
     return (
       <Component
         {...(props.data as T)}
+        {...(errorContext ? { context: errorContext } : {})}
         hasError={props?.hasError}
         error={props?.error}
       />