gt-react 10.0.9 → 10.1.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import React__default from 'react';
+import React__default, { ReactNode } from 'react';
 import { GTProp, Variable, VariableType, JsxChildren, CustomMapping } from 'generaltranslation/types';
 import * as generaltranslation from 'generaltranslation';
 import { GT } from 'generaltranslation';
@@ -90,6 +90,8 @@ type GTContextType = {
     locales: string[];
     setLocale: (locale: string) => void;
     defaultLocale: string;
+    region: string | undefined;
+    setRegion: (region: string | undefined) => void;
     translations: Translations | null;
     translationsStatus: TranslationsStatus | null;
     translationRequired: boolean;
@@ -150,6 +152,7 @@ type GTProviderProps = {
     locales?: string[];
     defaultLocale?: string;
     locale?: string;
+    region?: string;
     cacheUrl?: string;
     runtimeUrl?: string;
     renderSettings?: {
@@ -174,6 +177,7 @@ type ClientProviderProps = {
     initialTranslationsStatus: TranslationsStatus;
     locale: string;
     locales: string[];
+    region?: string;
     _versionId?: string;
     dictionaryEnabled?: boolean;
     defaultLocale: string;
@@ -193,7 +197,7 @@ type ClientProviderProps = {
     customMapping?: CustomMapping;
 };
 
-declare function ClientProvider({ children, dictionary, initialTranslations, initialTranslationsStatus, locale: _locale, _versionId, defaultLocale, translationRequired, dialectTranslationRequired, locales, renderSettings, projectId, devApiKey, runtimeUrl, runtimeTranslationEnabled, resetLocaleCookieName, localeCookieName, customMapping, }: ClientProviderProps): React$1.JSX.Element;
+declare function ClientProvider({ children, dictionary, initialTranslations, initialTranslationsStatus, locale: _locale, region: _region, _versionId, defaultLocale, translationRequired, dialectTranslationRequired, locales, renderSettings, projectId, devApiKey, runtimeUrl, runtimeTranslationEnabled, resetLocaleCookieName, localeCookieName, customMapping, }: ClientProviderProps): React$1.JSX.Element;
 
 /**
  * The `<Branch>` component dynamically renders a specified branch of content or a fallback child component.
@@ -494,6 +498,25 @@ declare function LocaleSelector({ locales: _locales, customNames, ...props }: {
     [key: string]: any;
 }): React__default.JSX.Element | null;
 
+/**
+ * A multi-purpose dropdown component that allows users to select a region.
+ */
+declare function RegionSelector<Regions extends string[]>({ regions: _regions, placeholder, customMapping, prioritizeCurrentLocaleRegion, sortRegionsAlphabetically, asLocaleSelector, ...props }: {
+    regions?: Regions;
+    placeholder?: ReactNode;
+    customMapping?: {
+        [region: string]: string | {
+            name?: string;
+            locale?: string;
+            emoji?: string;
+        };
+    };
+    prioritizeCurrentLocaleRegion?: boolean;
+    sortRegionsAlphabetically?: boolean;
+    asLocaleSelector?: boolean;
+    [key: string]: any;
+}): React__default.JSX.Element | null;
+
 /**
  * Provides General Translation context to its children, which can then access `useGT`, `useLocale`, and `useDefaultLocale`.
  *
@@ -516,7 +539,7 @@ declare function LocaleSelector({ locales: _locales, customNames, ...props }: {
  *
  * @returns {JSX.Element} The provider component for General Translation context.
  */
-declare function GTProvider({ children, config, projectId: _projectId, devApiKey: _devApiKey, dictionary: _dictionary, locales, defaultLocale, cacheUrl, runtimeUrl, renderSettings, ssr, localeCookieName, locale: _locale, loadDictionary, loadTranslations, fallback, translations: _translations, _versionId, customMapping, ...metadata }: GTProviderProps): react_jsx_runtime.JSX.Element;
+declare function GTProvider({ children, config, projectId: _projectId, devApiKey: _devApiKey, dictionary: _dictionary, locales, defaultLocale, cacheUrl, runtimeUrl, renderSettings, ssr, localeCookieName, locale: _locale, region: _region, loadDictionary, loadTranslations, fallback, translations: _translations, _versionId, customMapping, ...metadata }: GTProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Sets the user's locale in the `<GTProvider>` context.
@@ -542,7 +565,7 @@ declare function useSetLocale(): (locale: string) => void;
 declare function useLocales(): string[];
 
 /**
- /**
+ *
  * Gets the list of properties for using a locale selector.
  * Provides locale management utilities for the application.
  * @param locales an optional list of locales to use for the drop down. These locales must be a subset of the locales provided by the `<GTProvider>` context. When not provided, the list of locales from the `<GTProvider>` context is used.
@@ -583,4 +606,59 @@ declare function useGTClass(): generaltranslation.GT;
  */
 declare function useLocaleProperties(locale: string): generaltranslation_dist_locales_getLocaleProperties.LocaleProperties;
 
-export { Branch, ClientProvider, Currency, DateTime, GTContext, GTProvider, LocaleSelector, Num, Plural, T, Var, renderVariable, useDefaultLocale, useGT, useGTClass, useLocale, useLocaleProperties, useLocaleSelector, useLocales, useRuntimeTranslation, useSetLocale, useTranslations };
+/**
+ * A React hook that retrieves the user's currently selected region from the `<GTProvider>` context.
+ *
+ * Returns the `region` value as a string (e.g., `"US"`, `"CA"`) or `undefined` if no region has been set.
+ *
+ * ⚠️ **Note:** This hook must be used within a `<GTProvider>` component.
+ * If used outside, it will throw an error:
+ * `"useRegion(): Unable to access user's region outside of a <GTProvider>"`.
+ *
+ * @returns {string | undefined} The currently active region code, or `undefined` if not set.
+ *
+ * @example
+ * ```tsx
+ * const region = useRegion();
+ *
+ * if (!region) {
+ *   console.log("No region set yet");
+ * } else {
+ *   console.log(`Current region: ${region}`);
+ * }
+ * ```
+ */
+declare function useRegion(): string | undefined;
+
+type RegionData = {
+    code: string;
+    name: string;
+    emoji: string;
+    locale: string;
+};
+/**
+ * A multi-purpose dropdown component that allows users to select a region.
+ */
+declare function useRegionSelector({ regions: _regions, customMapping, prioritizeCurrentLocaleRegion, sortRegionsAlphabetically, }?: {
+    regions?: string[];
+    customMapping?: {
+        [region: string]: string | {
+            name?: string;
+            emoji?: string;
+            locale?: string;
+        };
+    };
+    prioritizeCurrentLocaleRegion?: boolean;
+    sortRegionsAlphabetically?: boolean;
+}): {
+    region: string | undefined;
+    setRegion: (region: string | undefined) => void;
+    regions: string[];
+    regionData: Map<string, RegionData>;
+    locales: string[];
+    locale: string;
+    localeRegion: string;
+    setLocale: (locale: string) => void;
+};
+
+export { Branch, ClientProvider, Currency, DateTime, GTContext, GTProvider, LocaleSelector, Num, Plural, RegionSelector, T, Var, renderVariable, useDefaultLocale, useGT, useGTClass, useLocale, useLocaleProperties, useLocaleSelector, useLocales, useRegion, useRegionSelector, useRuntimeTranslation, useSetLocale, useTranslations };

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,qBAAqB,MAAM,wCAAwC,CAAC;AAC3E,OAAO,cAAc,MAAM,4BAA4B,CAAC;AACxD,OAAO,cAAc,MAAM,2BAA2B,CAAC;AACvD,OAAO,MAAM,MAAM,mBAAmB,CAAC;AACvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,KAAK,MAAM,2BAA2B,CAAC;AAC9C,OAAO,gBAAgB,MAAM,0BAA0B,CAAC;AACxD,OAAO,eAAe,MAAM,qCAAqC,CAAC;AAClE,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,CAAC,MAAM,wBAAwB,CAAC;AACvC,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAClC,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAClC,OAAO,cAAc,MAAM,qBAAqB,CAAC;AACjD,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,YAAY,MAAM,sBAAsB,CAAC;AAChD,OAAO,UAAU,MAAM,oBAAoB,CAAC;AAC5C,OAAO,iBAAiB,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAErE,OAAO,EACL,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,KAAK,EACL,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,CAAC,EACD,GAAG,EACH,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,MAAM,EACN,cAAc,GACf,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,qBAAqB,MAAM,wCAAwC,CAAC;AAC3E,OAAO,cAAc,MAAM,4BAA4B,CAAC;AACxD,OAAO,cAAc,MAAM,2BAA2B,CAAC;AACvD,OAAO,MAAM,MAAM,mBAAmB,CAAC;AACvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,KAAK,MAAM,2BAA2B,CAAC;AAC9C,OAAO,gBAAgB,MAAM,0BAA0B,CAAC;AACxD,OAAO,eAAe,MAAM,qCAAqC,CAAC;AAClE,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,CAAC,MAAM,wBAAwB,CAAC;AACvC,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAClC,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAClC,OAAO,cAAc,MAAM,qBAAqB,CAAC;AACjD,OAAO,cAAc,MAAM,qBAAqB,CAAC;AACjD,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,YAAY,MAAM,sBAAsB,CAAC;AAChD,OAAO,UAAU,MAAM,oBAAoB,CAAC;AAC5C,OAAO,iBAAiB,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EACL,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,KAAK,EACL,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,CAAC,EACD,GAAG,EACH,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,MAAM,EACN,cAAc,EACd,cAAc,GACf,CAAC"}