gt-react 10.1.0 → 10.1.1

package/dist/client.d.ts

@@ -194,10 +194,11 @@ type ClientProviderProps = {
     gtServicesEnabled?: boolean;
     localeCookieName?: string;
     resetLocaleCookieName: string;
+    regionCookieName?: string;
     customMapping?: CustomMapping;
 };
 
-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;
+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.
@@ -486,20 +487,40 @@ 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 multi-purpose dropdown component that allows users to select a region.
+ * 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;
@@ -611,10 +632,6 @@ declare function useLocaleProperties(locale: string): generaltranslation_dist_lo
  *
  * 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
@@ -637,7 +654,57 @@ type RegionData = {
     locale: string;
 };
 /**
- * A multi-purpose dropdown component that allows users to select a region.
+ * 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[];