gt-react 10.0.9 → 10.1.1

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;
@@ -190,10 +194,11 @@ type ClientProviderProps = {
     gtServicesEnabled?: boolean;
     localeCookieName?: string;
     resetLocaleCookieName: string;
+    regionCookieName?: string;
     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, regionCookieName, customMapping, }: ClientProviderProps): React$1.JSX.Element;
 
 /**
  * The `<Branch>` component dynamically renders a specified branch of content or a fallback child component.
@@ -482,15 +487,54 @@ declare namespace Var {
 
 /**
  * A dropdown component that allows users to select a locale.
- * @param {string[]} locales - An optional list of locales to use for the dropdown. If not provided, the list of locales from the `<GTProvider>` context is used.
- * @param {object} customNames - An optional object to map locales to custom names.
+ * @param {string[]} [locales] - An optional list of locales to use for the dropdown. If not provided, the list of locales from the `<GTProvider>` context is used.
+ * @param {object} [customNames] - (deprecated) An optional object to map locales to custom names. Use `customMapping` instead.
+ * @param {CustomMapping} [customMapping] - An optional object to map locales to custom display names, emojis, or other properties.
  * @returns {React.ReactElement | null} The rendered locale dropdown component or null to prevent rendering.
  */
-declare function LocaleSelector({ locales: _locales, customNames, ...props }: {
+declare function LocaleSelector({ locales: _locales, customNames, customMapping, ...props }: {
     locales?: string[];
     customNames?: {
         [key: string]: string;
     };
+    customMapping?: CustomMapping;
+    [key: string]: any;
+}): React__default.JSX.Element | null;
+
+/**
+ * A dropdown component that allows users to select a region.
+ *
+ * @param {string[]} [regions] - An optional array of ISO 3166 region codes to display. If not provided, regions are inferred from supported locales in the `<GTProvider>` context.
+ * @param {React.ReactNode} [placeholder] - Optional placeholder node to display as the first option when no region is selected.
+ * @param {object} [customMapping] - An optional object to map region codes to custom display names, emojis, or associated locales. The value can be a string (display name) or an object with `name`, `emoji`, and/or `locale` properties.
+ * @param {boolean} [prioritizeCurrentLocaleRegion] - If true, the region corresponding to the current locale is prioritized in the list.
+ * @param {boolean} [sortRegionsAlphabetically] - If true, regions are sorted alphabetically by display name.
+ * @param {boolean} [asLocaleSelector=false] - If true, selecting a region will also update the locale to the region's associated locale.
+ * @param {object} [props] - Additional props to pass to the underlying `<select>` element.
+ * @returns {React.JSX.Element | null} The rendered region dropdown component or null if no regions are available.
+ *
+ * @example
+ * ```tsx
+ * <RegionSelector
+ *   regions={['US', 'CA']}
+ *   customMapping={{ US: { name: "United States", emoji: "🇺🇸" } }}
+ *   placeholder="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;
 
@@ -516,7 +560,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 +586,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 +627,105 @@ 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.
+ *
+ * @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;
+};
+/**
+ * React hook for managing region selection logic in applications supporting multiple regions.
+ *
+ * This hook provides the necessary data and handlers to implement a region selector UI component.
+ * It returns the current region, a list of available regions, region metadata, and functions to update the region or associated locale.
+ *
+ * ### Parameters
+ * @param {Object} [options] - Optional configuration object.
+ * @param {string[]} [options.regions] - An optional array of ISO 3166 region codes to display. If not provided, regions are inferred from supported locales.
+ * @param {Object.<string, string|{name?: string, emoji?: string, locale?: string}>} [options.customMapping] - Optional mapping to override region display names, emojis, or associated locales.
+ * @param {boolean} [options.prioritizeCurrentLocaleRegion=true] - If true, the region corresponding to the current locale is prioritized in the list.
+ * @param {boolean} [options.sortRegionsAlphabetically=true] - If true, regions are sorted alphabetically by display name.
+ *
+ * ### Returns
+ * @returns {{
+ *   region: string | undefined,
+ *   setRegion: (region: string) => void,
+ *   regions: string[],
+ *   regionData: Map<string, { code: string, name: string, emoji: string, locale: string }>,
+ *   locale: string,
+ *   setLocale: (locale: string) => void
+ * }} An object containing:
+ *   - `region`: The currently selected region code.
+ *   - `setRegion`: Function to update the selected region.
+ *   - `regions`: Array of available region codes.
+ *   - `regionData`: Map of region codes to their display data (name, emoji, locale).
+ *   - `locale`: The current locale.
+ *   - `setLocale`: Function to update the locale.
+ *
+ * ### Example
+ * ```tsx
+ * const {
+ *   region,
+ *   setRegion,
+ *   regions,
+ *   regionData,
+ *   locale,
+ *   setLocale
+ * } = useRegionSelector({
+ *   customMapping: { US: { name: "United States", emoji: "🇺🇸" } }
+ * });
+ *
+ * return (
+ *   <select value={region} onChange={e => setRegion(e.target.value)}>
+ *     {regions.map(r => (
+ *       <option key={r} value={r}>
+ *         {regionData.get(r)?.name}
+ *       </option>
+ *     ))}
+ *   </select>
+ * );
+ * ```
+ */
+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"}