react-intlayer 9.1.0 → 9.1.2

package/dist/esm/client/useDictionaryDynamic.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionaryDynamic.mjs","names":["loadDynamicChunk"],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["'use client';\n\nimport { internationalization } from '@intlayer/config/built';\nimport {\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveQualifiedDynamicContent,\n} from '@intlayer/core/dictionaryManipulator';\nimport type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { useContext } from 'react';\nimport { getDictionary } from '../getDictionary';\nimport { IntlayerClientContext } from './IntlayerProvider';\n// `useLoadDynamic` is a suspender cache, not a React hook — aliased to a\n// non-hook name so it can be invoked in loops / conditionally (e.g. when a\n// collection loads several chunks at once).\nimport { useLoadDynamic as loadDynamicChunk } from './useLoadDynamic';\n\n/**\n * Client-side hook that lazily loads a dictionary and returns its content.\n *\n * The dictionary entry is either a plain dynamic loader map\n * (`locale → loader`) or a qualified one (`locale → qualifierId → loader`,\n * tagged with the qualifier dimension). For qualified maps, only the chunk(s)\n * the selector targets are loaded; the resolution mirrors static mode.\n *\n * If the locale is not provided (directly or through the selector), the client\n * context locale is used.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<K> = LocalesValues,\n>(\n  dictionaryPromise:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: K,\n  localeOrSelector?: A\n) => {\n  const { locale: currentLocale } = useContext(IntlayerClientContext) ?? {};\n\n  const { locale: selectorLocale, selector } =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false'\n      ? parseDictionarySelector<LocalesValues>(localeOrSelector)\n      : {\n          locale: localeOrSelector as LocalesValues | undefined,\n          selector: undefined,\n        };\n\n  const localeTarget =\n    selectorLocale ?? currentLocale ?? internationalization.defaultLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    isQualifiedDynamicLoaderMap(dictionaryPromise)\n  ) {\n    return resolveQualifiedDynamicContent({\n      loaderMap: dictionaryPromise,\n      key: String(key),\n      locale: localeTarget,\n      selector,\n      loadChunk: (cacheKey, promise) => loadDynamicChunk(cacheKey, promise),\n      transform: (dictionary) => getDictionary(dictionary, localeTarget),\n    });\n  }\n\n  const plainLoaders = dictionaryPromise as StrictModeLocaleMap<\n    () => Promise<T>\n  >;\n\n  const dictionary = loadDynamicChunk<T>(\n    `${String(key)}.${localeTarget}`,\n    plainLoaders[localeTarget as keyof typeof plainLoaders]?.() as Promise<T>\n  );\n\n  return getDictionary(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,wBAKX,mBAGA,KACA,qBACG;CACH,MAAM,EAAE,QAAQ,kBAAkB,WAAW,qBAAqB,KAAK,CAAC;CAExE,MAAM,EAAE,QAAQ,gBAAgB,aAC9B,QAAQ,IAAI,iCAAiC,UACzC,wBAAuC,gBAAgB,IACvD;EACE,QAAQ;EACR,UAAU;CACZ;CAEN,MAAM,eACJ,kBAAkB,iBAAiB,qBAAqB;CAE1D,IACE,QAAQ,IAAI,iCAAiC,WAC7C,4BAA4B,iBAAiB,GAE7C,OAAO,+BAA+B;EACpC,WAAW;EACX,KAAK,OAAO,GAAG;EACf,QAAQ;EACR;EACA,YAAY,UAAU,YAAYA,eAAiB,UAAU,OAAO;EACpE,YAAY,eAAe,cAAc,YAAY,YAAY;CACnE,CAAC;CAGH,MAAM,eAAe;CASrB,OAAO,cALYA,eACjB,GAAG,OAAO,GAAG,EAAE,GAAG,gBAClB,aAAa,aAA0C,GAAG,CAG9B,GAAG,YAAY;AAC/C"}
+{"version":3,"file":"useDictionaryDynamic.mjs","names":["loadDynamicChunk"],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["'use client';\n\nimport { internationalization } from '@intlayer/config/built';\nimport {\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveDictionaryArgument,\n  resolveQualifiedDynamicContent,\n} from '@intlayer/core/dictionaryManipulator';\nimport type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { useContext } from 'react';\nimport { getDictionary } from '../getDictionary';\nimport { IntlayerClientContext } from './IntlayerProvider';\n// `useLoadDynamic` is a suspender cache, not a React hook — aliased to a\n// non-hook name so it can be invoked in loops / conditionally (e.g. when a\n// collection loads several chunks at once).\nimport { useLoadDynamic as loadDynamicChunk } from './useLoadDynamic';\n\n/**\n * Client-side hook that lazily loads a dictionary and returns its content.\n *\n * The dictionary entry is either a plain dynamic loader map\n * (`locale → loader`) or a qualified one (`locale → qualifierId → loader`,\n * tagged with the qualifier dimension). For qualified maps, only the chunk(s)\n * the selector targets are loaded; the resolution mirrors static mode.\n *\n * If the locale is not provided (directly or through the selector), the client\n * context locale is used.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForKey<K> = DeclaredLocales,\n>(\n  dictionaryPromise:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: K,\n  localeOrSelector?: A\n) => {\n  const { locale: currentLocale, variant: contextVariant } =\n    useContext(IntlayerClientContext) ?? {};\n\n  const { locale: selectorLocale, selector } =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false'\n      ? parseDictionarySelector<LocalesValues>(\n          // Layers the provider's ambient variant under the call-site argument\n          // before the chunk walk, so only the targeted chunk is loaded.\n          resolveDictionaryArgument({\n            localeOrSelector,\n            contextLocale: currentLocale,\n            contextVariant,\n            dictionaryKey: String(key),\n          })\n        )\n      : {\n          locale: localeOrSelector as LocalesValues | undefined,\n          selector: undefined,\n        };\n\n  const localeTarget =\n    selectorLocale ?? currentLocale ?? internationalization.defaultLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    isQualifiedDynamicLoaderMap(dictionaryPromise)\n  ) {\n    return resolveQualifiedDynamicContent({\n      loaderMap: dictionaryPromise,\n      key: String(key),\n      locale: localeTarget,\n      selector,\n      loadChunk: (cacheKey, promise) => loadDynamicChunk(cacheKey, promise),\n      transform: (dictionary) => getDictionary(dictionary, localeTarget),\n    });\n  }\n\n  const plainLoaders = dictionaryPromise as StrictModeLocaleMap<\n    () => Promise<T>\n  >;\n\n  const dictionary = loadDynamicChunk<T>(\n    `${String(key)}.${localeTarget}`,\n    plainLoaders[localeTarget as keyof typeof plainLoaders]?.() as Promise<T>\n  );\n\n  return getDictionary(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqCA,MAAa,wBAOX,mBAGA,KACA,qBACG;CACH,MAAM,EAAE,QAAQ,eAAe,SAAS,mBACtC,WAAW,qBAAqB,KAAK,CAAC;CAExC,MAAM,EAAE,QAAQ,gBAAgB,aAC9B,QAAQ,IAAI,iCAAiC,UACzC,wBAGE,0BAA0B;EACxB;EACA,eAAe;EACf;EACA,eAAe,OAAO,GAAG;CAC3B,CAAC,CACH,IACA;EACE,QAAQ;EACR,UAAU;CACZ;CAEN,MAAM,eACJ,kBAAkB,iBAAiB,qBAAqB;CAE1D,IACE,QAAQ,IAAI,iCAAiC,WAC7C,4BAA4B,iBAAiB,GAE7C,OAAO,+BAA+B;EACpC,WAAW;EACX,KAAK,OAAO,GAAG;EACf,QAAQ;EACR;EACA,YAAY,UAAU,YAAYA,eAAiB,UAAU,OAAO;EACpE,YAAY,eAAe,cAAc,YAAY,YAAY;CACnE,CAAC;CAGH,MAAM,eAAe;CASrB,OAAO,cALYA,eACjB,GAAG,OAAO,GAAG,EAAE,GAAG,gBAClB,aAAa,aAA0C,GAAG,CAG9B,GAAG,YAAY;AAC/C"}

package/dist/esm/client/useI18n.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useI18n.mjs","names":[],"sources":["../../../src/client/useI18n.ts"],"sourcesContent":["'use client';\n\nimport { getIntlayer } from '@intlayer/core/interpreter';\nimport type { ValidDotPathsFor } from '@intlayer/core/transpiler';\nimport type { GetSubPath } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryContent,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { useContext, useMemo } from 'react';\nimport type { DeepTransformContent } from '../plugins';\nimport { IntlayerClientContext } from './IntlayerProvider';\n\n/**\n * Hook that provides a translation function `t()` for accessing nested content by key.\n * This hook mimics the pattern found in libraries like i18next, next-intl, and vue-i18n.\n *\n * @param namespace - The dictionary key to scope translations to\n * @param locale - Optional locale override. If not provided, uses the current context locale\n * @returns A translation function `t(key)` that returns the translated content for the given key\n *\n * @example\n * ```tsx\n * const t = useI18n('IndexPage');\n * const title = t('title'); // Returns translated string for 'IndexPage.title'\n * const nestedContent = t('section.subtitle'); // Returns 'IndexPage.section.subtitle'\n * // For attributes like `aria-label`, use `.value` to get the plain string\n * const ariaLabel = t('button.ariaLabel').value; // 'Close modal'\n * ```\n */\nexport const useI18n = <\n  T extends DictionaryKeys,\n  L extends LocalesValues = DeclaredLocales,\n>(\n  namespace: T,\n  locale?: L\n) => {\n  const { locale: currentLocale } = useContext(IntlayerClientContext) ?? {};\n  const localeTarget = useMemo(\n    () => locale ?? currentLocale,\n    [currentLocale, locale]\n  );\n\n  // Get the dictionary content for the namespace\n  // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  const dictionaryContent: DeepTransformContent<DictionaryRegistryContent<T>> =\n    useMemo(\n      () => getIntlayer<T, L>(namespace, localeTarget as L),\n      [namespace, localeTarget]\n    );\n\n  // Return the translation function\n  // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  const t = <P extends ValidDotPathsFor<T>>(\n    path: P\n    // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  ): GetSubPath<DeepTransformContent<DictionaryRegistryContent<T>>, P> => {\n    if (!path) {\n      // @ts-ignore Type instantiation is excessively deep and possibly infinite\n      return dictionaryContent as any;\n    }\n\n    const pathArray = (path as string).split('.');\n    let current: any = dictionaryContent;\n\n    for (const key of pathArray) {\n      current = current?.[key];\n      if (current === undefined) {\n        // Return the whole dictionary as fallback if path is not found\n        return dictionaryContent as any;\n      }\n    }\n\n    return current;\n  };\n\n  return t;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,WAIX,WACA,WACG;CACH,MAAM,EAAE,QAAQ,kBAAkB,WAAW,qBAAqB,KAAK,CAAC;CACxE,MAAM,eAAe,cACb,UAAU,eAChB,CAAC,eAAe,MAAM,CACxB;CAIA,MAAM,oBACJ,cACQ,YAAkB,WAAW,YAAiB,GACpD,CAAC,WAAW,YAAY,CAC1B;CAIF,MAAM,KACJ,SAEsE;EACtE,IAAI,CAAC,MAEH,OAAO;EAGT,MAAM,YAAa,KAAgB,MAAM,GAAG;EAC5C,IAAI,UAAe;EAEnB,KAAK,MAAM,OAAO,WAAW;GAC3B,UAAU,UAAU;GACpB,IAAI,YAAY,QAEd,OAAO;EAEX;EAEA,OAAO;CACT;CAEA,OAAO;AACT"}
+{"version":3,"file":"useI18n.mjs","names":[],"sources":["../../../src/client/useI18n.ts"],"sourcesContent":["'use client';\n\nimport { getIntlayer } from '@intlayer/core/interpreter';\nimport type { ValidDotPathsFor } from '@intlayer/core/transpiler';\nimport type { GetSubPath } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryContent,\n} from '@intlayer/types/module_augmentation';\nimport { useContext, useMemo } from 'react';\nimport type { DeepTransformContent } from '../plugins';\nimport { IntlayerClientContext } from './IntlayerProvider';\n\n/**\n * Hook that provides a translation function `t()` for accessing nested content by key.\n * This hook mimics the pattern found in libraries like i18next, next-intl, and vue-i18n.\n *\n * @param namespace - The dictionary key to scope translations to\n * @param locale - Optional locale override. If not provided, uses the current context locale\n * @returns A translation function `t(key)` that returns the translated content for the given key\n *\n * @example\n * ```tsx\n * const t = useI18n('IndexPage');\n * const title = t('title'); // Returns translated string for 'IndexPage.title'\n * const nestedContent = t('section.subtitle'); // Returns 'IndexPage.section.subtitle'\n * // For attributes like `aria-label`, use `.value` to get the plain string\n * const ariaLabel = t('button.ariaLabel').value; // 'Close modal'\n * ```\n */\nexport const useI18n = <\n  T extends DictionaryKeys,\n  L extends DeclaredLocales = DeclaredLocales,\n>(\n  namespace: T,\n  locale?: L\n) => {\n  const { locale: currentLocale } = useContext(IntlayerClientContext) ?? {};\n  const localeTarget = useMemo(\n    () => locale ?? currentLocale,\n    [currentLocale, locale]\n  );\n\n  // Get the dictionary content for the namespace\n  // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  const dictionaryContent: DeepTransformContent<DictionaryRegistryContent<T>> =\n    useMemo(\n      () => getIntlayer<T, L>(namespace, localeTarget as L),\n      [namespace, localeTarget]\n    );\n\n  // Return the translation function\n  // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  const t = <P extends ValidDotPathsFor<T>>(\n    path: P\n    // @ts-ignore Type instantiation is excessively deep and possibly infinite\n  ): GetSubPath<DeepTransformContent<DictionaryRegistryContent<T>>, P> => {\n    if (!path) {\n      // @ts-ignore Type instantiation is excessively deep and possibly infinite\n      return dictionaryContent as any;\n    }\n\n    const pathArray = (path as string).split('.');\n    let current: any = dictionaryContent;\n\n    for (const key of pathArray) {\n      current = current?.[key];\n      if (current === undefined) {\n        // Return the whole dictionary as fallback if path is not found\n        return dictionaryContent as any;\n      }\n    }\n\n    return current;\n  };\n\n  return t;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,WAIX,WACA,WACG;CACH,MAAM,EAAE,QAAQ,kBAAkB,WAAW,qBAAqB,KAAK,CAAC;CACxE,MAAM,eAAe,cACb,UAAU,eAChB,CAAC,eAAe,MAAM,CACxB;CAIA,MAAM,oBACJ,cACQ,YAAkB,WAAW,YAAiB,GACpD,CAAC,WAAW,YAAY,CAC1B;CAIF,MAAM,KACJ,SAEsE;EACtE,IAAI,CAAC,MAEH,OAAO;EAGT,MAAM,YAAa,KAAgB,MAAM,GAAG;EAC5C,IAAI,UAAe;EAEnB,KAAK,MAAM,OAAO,WAAW;GAC3B,UAAU,UAAU;GACpB,IAAI,YAAY,QAEd,OAAO;EAEX;EAEA,OAAO;CACT;CAEA,OAAO;AACT"}

package/dist/esm/client/useIntlayer.mjs

@@ -3,7 +3,7 @@
 import { getIntlayer } from "../getIntlayer.mjs";
 import { IntlayerClientContext } from "./IntlayerProvider.mjs";
 import { useContext, useMemo } from "react";
-import { getDictionarySelectorCacheKey } from "@intlayer/core/dictionaryManipulator";
+import { getDictionarySelectorCacheKey, resolveDictionaryArgument } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/client/useIntlayer.ts
 /**
@@ -12,8 +12,12 @@ import { getDictionarySelectorCacheKey } from "@intlayer/core/dictionaryManipula
 * The second argument is either a locale or a selector object:
 * - `{ item: 2 }` — collection item (omit `item` to get every item as array)
 * - `{ variant: 'black-friday' }` — named variant (omit for the `default` one)
+* - `{ variant: ['black-friday', 'promo'] }` — ordered preference chain
 * - `locale` composes with any selector and overrides the context locale
 *
+* `locale` and `variant` both fall back to the surrounding `IntlayerProvider`
+* when the call does not pin them.
+*
 * @param key - The unique key of the dictionary to retrieve.
 * @param localeOrSelector - Optional locale or selector.
 * @returns The dictionary content for the resolved entry and locale.
@@ -31,19 +35,14 @@ import { getDictionarySelectorCacheKey } from "@intlayer/core/dictionaryManipula
 * ```
 */
 const useIntlayer = (key, localeOrSelector) => {
-	const { locale: currentLocale } = useContext(IntlayerClientContext) ?? {};
-	const isSelector = process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" && typeof localeOrSelector === "object" && localeOrSelector !== null;
-	return useMemo(() => {
-		if (isSelector) return getIntlayer(key, {
-			...localeOrSelector,
-			locale: localeOrSelector.locale ?? currentLocale
-		});
-		return getIntlayer(key, localeOrSelector ?? currentLocale);
-	}, [
-		key,
-		currentLocale,
-		isSelector ? `${localeOrSelector.locale ?? ""}|${getDictionarySelectorCacheKey(localeOrSelector)}` : localeOrSelector
-	]);
+	const { locale: currentLocale, variant: contextVariant } = useContext(IntlayerClientContext) ?? {};
+	const argument = process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" ? resolveDictionaryArgument({
+		localeOrSelector,
+		contextLocale: currentLocale,
+		contextVariant,
+		dictionaryKey: key
+	}) : localeOrSelector ?? currentLocale;
+	return useMemo(() => getIntlayer(key, argument), [key, typeof argument === "object" && argument !== null ? `${argument.locale ?? ""}|${getDictionarySelectorCacheKey(argument)}` : argument]);
 };
 
 //#endregion

package/dist/esm/client/useIntlayer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["'use client';\n\nimport { getDictionarySelectorCacheKey } from '@intlayer/core/dictionaryManipulator';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { useContext, useMemo } from 'react';\nimport { getIntlayer } from '../getIntlayer';\nimport { IntlayerClientContext } from './IntlayerProvider';\n\n/**\n * Client-side hook that picks one dictionary by its key and returns its content.\n *\n * The second argument is either a locale or a selector object:\n * - `{ item: 2 }` — collection item (omit `item` to get every item as array)\n * - `{ variant: 'black-friday' }` — named variant (omit for the `default` one)\n * - `locale` composes with any selector and overrides the context locale\n *\n * @param key - The unique key of the dictionary to retrieve.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The dictionary content for the resolved entry and locale.\n *\n * @example\n * ```tsx\n * import { useIntlayer } from 'react-intlayer';\n *\n * const MyComponent = () => {\n *   const content = useIntlayer('my-dictionary-key');\n *   const faq2 = useIntlayer('faq', { item: 2 });\n *\n *   return <div>{content.myField.value}</div>;\n * };\n * ```\n */\nexport const useIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A\n) => {\n  const { locale: currentLocale } = useContext(IntlayerClientContext) ?? {};\n\n  const isSelector =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    typeof localeOrSelector === 'object' &&\n    localeOrSelector !== null;\n\n  // Stable identity of the second argument for memoization\n  const localeOrSelectorIdentity = isSelector\n    ? `${localeOrSelector.locale ?? ''}|${getDictionarySelectorCacheKey(localeOrSelector)}`\n    : localeOrSelector;\n\n  return useMemo(() => {\n    if (isSelector) {\n      return getIntlayer(key, {\n        ...localeOrSelector,\n        locale: localeOrSelector.locale ?? currentLocale,\n      } as A);\n    }\n\n    const localeTarget = (localeOrSelector ?? currentLocale) as A;\n\n    return getIntlayer<T, A>(key, localeTarget);\n  }, [key, currentLocale, localeOrSelectorIdentity]);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAa,eAIX,KACA,qBACG;CACH,MAAM,EAAE,QAAQ,kBAAkB,WAAW,qBAAqB,KAAK,CAAC;CAExE,MAAM,aACJ,QAAQ,IAAI,iCAAiC,WAC7C,OAAO,qBAAqB,YAC5B,qBAAqB;CAOvB,OAAO,cAAc;EACnB,IAAI,YACF,OAAO,YAAY,KAAK;GACtB,GAAG;GACH,QAAQ,iBAAiB,UAAU;EACrC,CAAM;EAKR,OAAO,YAAkB,KAFH,oBAAoB,aAEA;CAC5C,GAAG;EAAC;EAAK;EAfwB,aAC7B,GAAG,iBAAiB,UAAU,GAAG,GAAG,8BAA8B,gBAAgB,MAClF;CAa4C,CAAC;AACnD"}
+{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["'use client';\n\nimport {\n  getDictionarySelectorCacheKey,\n  resolveDictionaryArgument,\n} from '@intlayer/core/dictionaryManipulator';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionarySelectorForKey,\n} from '@intlayer/types/module_augmentation';\nimport { useContext, useMemo } from 'react';\nimport { getIntlayer } from '../getIntlayer';\nimport { IntlayerClientContext } from './IntlayerProvider';\n\n/**\n * Client-side hook that picks one dictionary by its key and returns its content.\n *\n * The second argument is either a locale or a selector object:\n * - `{ item: 2 }` — collection item (omit `item` to get every item as array)\n * - `{ variant: 'black-friday' }` — named variant (omit for the `default` one)\n * - `{ variant: ['black-friday', 'promo'] }` — ordered preference chain\n * - `locale` composes with any selector and overrides the context locale\n *\n * `locale` and `variant` both fall back to the surrounding `IntlayerProvider`\n * when the call does not pin them.\n *\n * @param key - The unique key of the dictionary to retrieve.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The dictionary content for the resolved entry and locale.\n *\n * @example\n * ```tsx\n * import { useIntlayer } from 'react-intlayer';\n *\n * const MyComponent = () => {\n *   const content = useIntlayer('my-dictionary-key');\n *   const faq2 = useIntlayer('faq', { item: 2 });\n *\n *   return <div>{content.myField.value}</div>;\n * };\n * ```\n */\nexport const useIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A\n) => {\n  const { locale: currentLocale, variant: contextVariant } =\n    useContext(IntlayerClientContext) ?? {};\n\n  // Layers the provider's locale and variant under the call-site argument.\n  // Selectors disabled project-wide (build-time flag) ⇒ the argument can only\n  // be a locale, so the merge is dead code and is dropped by the bundler.\n  const argument =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false'\n      ? resolveDictionaryArgument({\n          localeOrSelector,\n          contextLocale: currentLocale,\n          contextVariant,\n          dictionaryKey: key as string,\n        })\n      : (localeOrSelector ?? currentLocale);\n\n  // Stable identity of the resolved argument for memoization — a provider\n  // variant is often a fresh object literal on every render, so the dependency\n  // has to be its serialization, never its reference.\n  const argumentIdentity =\n    typeof argument === 'object' && argument !== null\n      ? `${argument.locale ?? ''}|${getDictionarySelectorCacheKey(argument)}`\n      : argument;\n\n  return useMemo(\n    () => getIntlayer<T, A>(key, argument as A),\n    [key, argumentIdentity]\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,MAAa,eAMX,KACA,qBACG;CACH,MAAM,EAAE,QAAQ,eAAe,SAAS,mBACtC,WAAW,qBAAqB,KAAK,CAAC;CAKxC,MAAM,WACJ,QAAQ,IAAI,iCAAiC,UACzC,0BAA0B;EACxB;EACA,eAAe;EACf;EACA,eAAe;CACjB,CAAC,IACA,oBAAoB;CAU3B,OAAO,cACC,YAAkB,KAAK,QAAa,GAC1C,CAAC,KAND,OAAO,aAAa,YAAY,aAAa,OACzC,GAAG,SAAS,UAAU,GAAG,GAAG,8BAA8B,QAAQ,MAClE,QAIkB,CACxB;AACF"}

package/dist/esm/getDictionary.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"getDictionary.mjs","names":["getDictionaryCore"],"sources":["../../src/getDictionary.ts"],"sourcesContent":["import { getDictionary as getDictionaryCore } from '@intlayer/core/interpreter';\nimport type {\n  Dictionary,\n  DictionarySelectorForGroup,\n  QualifiedDictionaryGroup,\n  ResolveQualifiedDictionaryContent,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\n/**\n * Transforms a dictionary (or qualified dictionary group) and returns its\n * content for the given locale or selector (`{ item }`, `{ variant }`,\n * optionally combined with `locale`).\n */\nexport const getDictionary = <\n  const T extends Dictionary | QualifiedDictionaryGroup,\n  const A extends\n    | LocalesValues\n    | DictionarySelectorForGroup<T> = DeclaredLocales,\n>(\n  dictionary: T,\n  localeOrSelector?: A\n): DeepTransformContent<\n  ResolveQualifiedDictionaryContent<T, A>,\n  ExtractSelectorLocale<A>\n> => {\n  const locale = (\n    typeof localeOrSelector === 'object' && localeOrSelector !== null\n      ? localeOrSelector.locale\n      : localeOrSelector\n  ) as LocalesValues | undefined;\n\n  return getDictionaryCore(\n    dictionary,\n    localeOrSelector,\n    getPlugins(locale)\n  ) as any;\n};\n"],"mappings":";;;;;;;;;AAmBA,MAAa,iBAMX,YACA,qBAIG;CAOH,OAAOA,gBACL,YACA,kBACA,WARA,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,gBAMa,CACnB;AACF"}
+{"version":3,"file":"getDictionary.mjs","names":["getDictionaryCore"],"sources":["../../src/getDictionary.ts"],"sourcesContent":["import { getDictionary as getDictionaryCore } from '@intlayer/core/interpreter';\nimport type {\n  Dictionary,\n  DictionarySelectorForGroup,\n  QualifiedDictionaryGroup,\n  ResolveQualifiedDictionaryContent,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\n/**\n * Transforms a dictionary (or qualified dictionary group) and returns its\n * content for the given locale or selector (`{ item }`, `{ variant }`,\n * optionally combined with `locale`).\n */\nexport const getDictionary = <\n  const T extends Dictionary | QualifiedDictionaryGroup,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForGroup<T> = DeclaredLocales,\n>(\n  dictionary: T,\n  localeOrSelector?: A\n): DeepTransformContent<\n  ResolveQualifiedDictionaryContent<T, A>,\n  ExtractSelectorLocale<A>\n> => {\n  const locale = (\n    typeof localeOrSelector === 'object' && localeOrSelector !== null\n      ? localeOrSelector.locale\n      : localeOrSelector\n  ) as LocalesValues | undefined;\n\n  return getDictionaryCore(\n    dictionary,\n    localeOrSelector,\n    getPlugins(locale)\n  ) as any;\n};\n"],"mappings":";;;;;;;;;AAmBA,MAAa,iBAMX,YACA,qBAIG;CAOH,OAAOA,gBACL,YACA,kBACA,WARA,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,gBAMa,CACnB;AACF"}

package/dist/esm/getIntlayer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"getIntlayer.mjs","names":["getIntlayerCore"],"sources":["../../src/getIntlayer.ts"],"sourcesContent":["import { getIntlayer as getIntlayerCore } from '@intlayer/core/interpreter';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryResult,\n  DictionarySelectorForKey,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\n/**\n * Picks one dictionary by its key and returns its content for the given\n * locale or selector (`{ item }`, `{ variant }`,\n * optionally combined with `locale`).\n */\nexport const getIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A\n): DeepTransformContent<\n  DictionaryRegistryResult<T, A>,\n  ExtractSelectorLocale<A>\n> => {\n  const locale = (\n    typeof localeOrSelector === 'object' && localeOrSelector !== null\n      ? localeOrSelector.locale\n      : localeOrSelector\n  ) as LocalesValues | undefined;\n\n  return getIntlayerCore(key, localeOrSelector, getPlugins(locale)) as any;\n};\n"],"mappings":";;;;;;;;;AAgBA,MAAa,eAIX,KACA,qBAIG;CAOH,OAAOA,cAAgB,KAAK,kBAAkB,WAL5C,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,gBAGyD,CAAC;AAClE"}
+{"version":3,"file":"getIntlayer.mjs","names":["getIntlayerCore"],"sources":["../../src/getIntlayer.ts"],"sourcesContent":["import { getIntlayer as getIntlayerCore } from '@intlayer/core/interpreter';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryResult,\n  DictionarySelectorForKey,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\n/**\n * Picks one dictionary by its key and returns its content for the given\n * locale or selector (`{ item }`, `{ variant }`,\n * optionally combined with `locale`).\n */\nexport const getIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A\n): DeepTransformContent<\n  DictionaryRegistryResult<T, A>,\n  ExtractSelectorLocale<A>\n> => {\n  const locale = (\n    typeof localeOrSelector === 'object' && localeOrSelector !== null\n      ? localeOrSelector.locale\n      : localeOrSelector\n  ) as LocalesValues | undefined;\n\n  return getIntlayerCore(key, localeOrSelector, getPlugins(locale)) as any;\n};\n"],"mappings":";;;;;;;;;AAgBA,MAAa,eAMX,KACA,qBAIG;CAOH,OAAOA,cAAgB,KAAK,kBAAkB,WAL5C,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,gBAGyD,CAAC;AAClE"}

package/dist/esm/server/IntlayerServerProvider.mjs

@@ -9,6 +9,13 @@ const { defaultLocale } = internationalization ?? {};
 */
 const IntlayerServerContext = createServerContext(defaultLocale);
 /**
+* Context that stores the ambient variant on the server side.
+*
+* Kept separate from {@link IntlayerServerContext} so the locale context keeps
+* its plain `LocalesValues` shape for the packages already reading it.
+*/
+const IntlayerServerVariantContext = createServerContext(void 0);
+/**
 * Hook that provides the current locale
 */
 const useIntlayer = () => getServerContext(IntlayerServerContext);
@@ -19,11 +26,14 @@ const locale = getServerContext(IntlayerServerContext);
 /**
 * Provider that store the current locale on the server side
 */
-const IntlayerServerProvider = ({ children, locale = defaultLocale }) => /* @__PURE__ */ jsx(IntlayerServerContext.Provider, {
+const IntlayerServerProvider = ({ children, locale = defaultLocale, variant }) => /* @__PURE__ */ jsx(IntlayerServerContext.Provider, {
 	value: locale,
-	children
+	children: /* @__PURE__ */ jsx(IntlayerServerVariantContext.Provider, {
+		value: variant,
+		children
+	})
 });
 
 //#endregion
-export { IntlayerServerContext, IntlayerServerProvider, locale, useIntlayer };
+export { IntlayerServerContext, IntlayerServerProvider, IntlayerServerVariantContext, locale, useIntlayer };
 //# sourceMappingURL=IntlayerServerProvider.mjs.map

package/dist/esm/server/IntlayerServerProvider.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"IntlayerServerProvider.mjs","names":[],"sources":["../../../src/server/IntlayerServerProvider.tsx"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport type { LocalesValues } from '@intlayer/types/module_augmentation';\n\nimport type { FC, PropsWithChildren } from 'react';\nimport { createServerContext, getServerContext } from './serverContext';\n\nconst { defaultLocale } = internationalization ?? {};\n\n/**\n * Context that store the current locale on the server side\n */\nexport const IntlayerServerContext =\n  createServerContext<LocalesValues>(defaultLocale);\n\n/**\n * Hook that provides the current locale\n */\nexport const useIntlayer = () => getServerContext(IntlayerServerContext);\n\n/**\n * Get the current locale\n */\nexport const locale = getServerContext(IntlayerServerContext);\n\nexport type IntlayerServerProviderProps = PropsWithChildren & {\n  locale?: LocalesValues;\n};\n\n/**\n * Provider that store the current locale on the server side\n */\nexport const IntlayerServerProvider: FC<IntlayerServerProviderProps> = ({\n  children,\n  locale = defaultLocale,\n}) => (\n  <IntlayerServerContext.Provider value={locale}>\n    {children}\n  </IntlayerServerContext.Provider>\n);\n"],"mappings":";;;;;AAMA,MAAM,EAAE,kBAAkB,wBAAwB,CAAC;;;;AAKnD,MAAa,wBACX,oBAAmC,aAAa;;;;AAKlD,MAAa,oBAAoB,iBAAiB,qBAAqB;;;;AAKvE,MAAa,SAAS,iBAAiB,qBAAqB;;;;AAS5D,MAAa,0BAA2D,EACtE,UACA,SAAS,oBAET,oBAAC,sBAAsB,UAAvB;CAAgC,OAAO;CACpC;AAC6B"}
+{"version":3,"file":"IntlayerServerProvider.mjs","names":[],"sources":["../../../src/server/IntlayerServerProvider.tsx"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport type {\n  LocalesValues,\n  ProviderVariant,\n} from '@intlayer/types/module_augmentation';\n\nimport type { FC, PropsWithChildren } from 'react';\nimport { createServerContext, getServerContext } from './serverContext';\n\nconst { defaultLocale } = internationalization ?? {};\n\n/**\n * Context that store the current locale on the server side\n */\nexport const IntlayerServerContext =\n  createServerContext<LocalesValues>(defaultLocale);\n\n/**\n * Context that stores the ambient variant on the server side.\n *\n * Kept separate from {@link IntlayerServerContext} so the locale context keeps\n * its plain `LocalesValues` shape for the packages already reading it.\n */\nexport const IntlayerServerVariantContext =\n  createServerContext<ProviderVariant>(undefined);\n\n/**\n * Hook that provides the current locale\n */\nexport const useIntlayer = () => getServerContext(IntlayerServerContext);\n\n/**\n * Get the current locale\n */\nexport const locale = getServerContext(IntlayerServerContext);\n\nexport type IntlayerServerProviderProps = PropsWithChildren & {\n  locale?: LocalesValues;\n  /**\n   * Ambient variant applied to every dictionary read below this provider — for\n   * a dimension resolved once per request (tenant, school type, plan tier…).\n   *\n   * Accepts a name (`'school1'`), an ordered preference chain\n   * (`['school1', 'default']`), or a per-key map\n   * (`{ key1: 'school1', default: 'base' }`). A call-site selector wins.\n   */\n  variant?: ProviderVariant;\n};\n\n/**\n * Provider that store the current locale on the server side\n */\nexport const IntlayerServerProvider: FC<IntlayerServerProviderProps> = ({\n  children,\n  locale = defaultLocale,\n  variant,\n}) => (\n  <IntlayerServerContext.Provider value={locale}>\n    <IntlayerServerVariantContext.Provider value={variant}>\n      {children}\n    </IntlayerServerVariantContext.Provider>\n  </IntlayerServerContext.Provider>\n);\n"],"mappings":";;;;;AASA,MAAM,EAAE,kBAAkB,wBAAwB,CAAC;;;;AAKnD,MAAa,wBACX,oBAAmC,aAAa;;;;;;;AAQlD,MAAa,+BACX,oBAAqC,MAAS;;;;AAKhD,MAAa,oBAAoB,iBAAiB,qBAAqB;;;;AAKvE,MAAa,SAAS,iBAAiB,qBAAqB;;;;AAkB5D,MAAa,0BAA2D,EACtE,UACA,SAAS,eACT,cAEA,oBAAC,sBAAsB,UAAvB;CAAgC,OAAO;WACrC,oBAAC,6BAA6B,UAA9B;EAAuC,OAAO;EAC3C;CACoC;AACT"}

package/dist/esm/server/useDictionary.mjs

@@ -1,6 +1,7 @@
 import { getDictionary } from "../getDictionary.mjs";
 import { getServerContext } from "./serverContext.mjs";
-import { IntlayerServerContext } from "./IntlayerServerProvider.mjs";
+import { IntlayerServerContext, IntlayerServerVariantContext } from "./IntlayerServerProvider.mjs";
+import { resolveDictionaryArgument } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/server/useDictionary.ts
 /**
@@ -12,10 +13,12 @@ import { IntlayerServerContext } from "./IntlayerServerProvider.mjs";
 */
 const useDictionary = (dictionary, localeOrSelector, fallbackLocale) => {
 	const contextLocale = getServerContext(IntlayerServerContext) ?? fallbackLocale;
-	if (process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" && typeof localeOrSelector === "object" && localeOrSelector !== null) return getDictionary(dictionary, {
-		...localeOrSelector,
-		locale: localeOrSelector.locale ?? contextLocale
-	});
+	if (process.env.INTLAYER_DICTIONARY_SELECTOR !== "false") return getDictionary(dictionary, resolveDictionaryArgument({
+		localeOrSelector,
+		contextLocale,
+		contextVariant: getServerContext(IntlayerServerVariantContext),
+		dictionaryKey: dictionary.key
+	}));
 	return getDictionary(dictionary, localeOrSelector ?? contextLocale);
 };
 

package/dist/esm/server/useDictionary.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionary.mjs","names":[],"sources":["../../../src/server/useDictionary.ts"],"sourcesContent":["import type {\n  Dictionary,\n  DictionarySelectorForGroup,\n  QualifiedDictionaryGroup,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport { IntlayerServerContext } from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n\n/**\n * On the server side, Hook that transform a dictionary (or qualified\n * dictionary group) and return the content\n *\n * If the locale is not provided (directly or through the selector), it will\n * use the locale from the server context\n */\nexport const useDictionary = <\n  const T extends Dictionary | QualifiedDictionaryGroup,\n  const A extends\n    | LocalesValues\n    | DictionarySelectorForGroup<T> = DeclaredLocales,\n>(\n  dictionary: T,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const contextLocale =\n    getServerContext<LocalesValues>(IntlayerServerContext) ?? fallbackLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    typeof localeOrSelector === 'object' &&\n    localeOrSelector !== null\n  ) {\n    return getDictionary(dictionary, {\n      ...localeOrSelector,\n      locale: localeOrSelector.locale ?? contextLocale,\n    } as A);\n  }\n\n  const localeTarget = (localeOrSelector ?? contextLocale) as A;\n\n  return getDictionary<T, A>(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;AAoBA,MAAa,iBAMX,YACA,kBACA,mBACG;CACH,MAAM,gBACJ,iBAAgC,qBAAqB,KAAK;CAE5D,IACE,QAAQ,IAAI,iCAAiC,WAC7C,OAAO,qBAAqB,YAC5B,qBAAqB,MAErB,OAAO,cAAc,YAAY;EAC/B,GAAG;EACH,QAAQ,iBAAiB,UAAU;CACrC,CAAM;CAKR,OAAO,cAAoB,YAFL,oBAAoB,aAES;AACrD"}
+{"version":3,"file":"useDictionary.mjs","names":[],"sources":["../../../src/server/useDictionary.ts"],"sourcesContent":["import { resolveDictionaryArgument } from '@intlayer/core/dictionaryManipulator';\nimport type {\n  Dictionary,\n  DictionarySelectorForGroup,\n  QualifiedDictionaryGroup,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n  ProviderVariant,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport {\n  IntlayerServerContext,\n  IntlayerServerVariantContext,\n} from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n\n/**\n * On the server side, Hook that transform a dictionary (or qualified\n * dictionary group) and return the content\n *\n * If the locale is not provided (directly or through the selector), it will\n * use the locale from the server context\n */\nexport const useDictionary = <\n  const T extends Dictionary | QualifiedDictionaryGroup,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForGroup<T> = DeclaredLocales,\n>(\n  dictionary: T,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const contextLocale =\n    getServerContext<LocalesValues>(IntlayerServerContext) ?? fallbackLocale;\n\n  if (process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false') {\n    const contextVariant = getServerContext<ProviderVariant>(\n      IntlayerServerVariantContext\n    );\n\n    return getDictionary<T, A>(\n      dictionary,\n      resolveDictionaryArgument({\n        localeOrSelector,\n        contextLocale,\n        contextVariant,\n        dictionaryKey: dictionary.key,\n      }) as A\n    );\n  }\n\n  const localeTarget = (localeOrSelector ?? contextLocale) as A;\n\n  return getDictionary<T, A>(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;AAyBA,MAAa,iBAMX,YACA,kBACA,mBACG;CACH,MAAM,gBACJ,iBAAgC,qBAAqB,KAAK;CAE5D,IAAI,QAAQ,IAAI,iCAAiC,SAK/C,OAAO,cACL,YACA,0BAA0B;EACxB;EACA;EACA,gBATmB,iBACrB,4BAQe;EACb,eAAe,WAAW;CAC5B,CAAC,CACH;CAKF,OAAO,cAAoB,YAFL,oBAAoB,aAES;AACrD"}

package/dist/esm/server/useDictionaryDynamic.mjs

@@ -1,9 +1,9 @@
 import { getDictionary } from "../getDictionary.mjs";
 import { getServerContext } from "./serverContext.mjs";
-import { IntlayerServerContext } from "./IntlayerServerProvider.mjs";
+import { IntlayerServerContext, IntlayerServerVariantContext } from "./IntlayerServerProvider.mjs";
 import { useLoadDynamic } from "./useLoadDynamic.mjs";
 import { internationalization } from "@intlayer/config/built";
-import { isQualifiedDynamicLoaderMap, parseDictionarySelector, resolveQualifiedDynamicContent } from "@intlayer/core/dictionaryManipulator";
+import { isQualifiedDynamicLoaderMap, parseDictionarySelector, resolveDictionaryArgument, resolveQualifiedDynamicContent } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/server/useDictionaryDynamic.ts
 /**
@@ -18,11 +18,17 @@ import { isQualifiedDynamicLoaderMap, parseDictionarySelector, resolveQualifiedD
 * context locale is used.
 */
 const useDictionaryDynamic = (dictionaryPromise, key, localeOrSelector, fallbackLocale) => {
-	const { locale: selectorLocale, selector } = process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" ? parseDictionarySelector(localeOrSelector) : {
+	const contextLocale = getServerContext(IntlayerServerContext);
+	const { locale: selectorLocale, selector } = process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" ? parseDictionarySelector(resolveDictionaryArgument({
+		localeOrSelector,
+		contextLocale,
+		contextVariant: getServerContext(IntlayerServerVariantContext),
+		dictionaryKey: String(key)
+	})) : {
 		locale: localeOrSelector,
 		selector: void 0
 	};
-	const localeTarget = selectorLocale ?? getServerContext(IntlayerServerContext) ?? fallbackLocale ?? internationalization.defaultLocale;
+	const localeTarget = selectorLocale ?? contextLocale ?? fallbackLocale ?? internationalization.defaultLocale;
 	if (process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" && isQualifiedDynamicLoaderMap(dictionaryPromise)) return resolveQualifiedDynamicContent({
 		loaderMap: dictionaryPromise,
 		key: String(key),

package/dist/esm/server/useDictionaryDynamic.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionaryDynamic.mjs","names":["loadDynamicChunk"],"sources":["../../../src/server/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport {\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveQualifiedDynamicContent,\n} from '@intlayer/core/dictionaryManipulator';\nimport type {\n  Dictionary,\n  DictionarySelector,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport { IntlayerServerContext } from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n// `useLoadDynamic` wraps `react.use`, which may be called in loops /\n// conditionally — aliased to a non-hook name so a collection can load several\n// chunks at once.\nimport { useLoadDynamic as loadDynamicChunk } from './useLoadDynamic';\n\n/**\n * Server-side hook that lazily loads a dictionary and returns its content.\n *\n * The dictionary entry is either a plain dynamic loader map\n * (`locale → loader`) or a qualified one (`locale → qualifierId → loader`,\n * tagged with the qualifier dimension). For qualified maps, only the chunk(s)\n * the selector targets are loaded; the resolution mirrors static mode.\n *\n * If the locale is not provided (directly or through the selector), the server\n * context locale is used.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const A extends LocalesValues | DictionarySelector = LocalesValues,\n>(\n  dictionaryPromise:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: string,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const { locale: selectorLocale, selector } =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false'\n      ? parseDictionarySelector<LocalesValues>(localeOrSelector)\n      : {\n          locale: localeOrSelector as LocalesValues | undefined,\n          selector: undefined,\n        };\n\n  const localeTarget =\n    selectorLocale ??\n    getServerContext<LocalesValues>(IntlayerServerContext) ??\n    fallbackLocale ??\n    internationalization.defaultLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    isQualifiedDynamicLoaderMap(dictionaryPromise)\n  ) {\n    return resolveQualifiedDynamicContent({\n      loaderMap: dictionaryPromise,\n      key: String(key),\n      locale: localeTarget,\n      selector,\n      loadChunk: (cacheKey, promise) => loadDynamicChunk(cacheKey, promise),\n      transform: (dictionary) => getDictionary(dictionary, localeTarget),\n    });\n  }\n\n  const plainLoaders = dictionaryPromise as StrictModeLocaleMap<\n    () => Promise<T>\n  >;\n\n  const dictionary = loadDynamicChunk<T>(\n    `${String(key)}.${localeTarget}`,\n    plainLoaders[localeTarget as keyof typeof plainLoaders]?.() as Promise<T>\n  );\n\n  return getDictionary(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmCA,MAAa,wBAIX,mBAGA,KACA,kBACA,mBACG;CACH,MAAM,EAAE,QAAQ,gBAAgB,aAC9B,QAAQ,IAAI,iCAAiC,UACzC,wBAAuC,gBAAgB,IACvD;EACE,QAAQ;EACR,UAAU;CACZ;CAEN,MAAM,eACJ,kBACA,iBAAgC,qBAAqB,KACrD,kBACA,qBAAqB;CAEvB,IACE,QAAQ,IAAI,iCAAiC,WAC7C,4BAA4B,iBAAiB,GAE7C,OAAO,+BAA+B;EACpC,WAAW;EACX,KAAK,OAAO,GAAG;EACf,QAAQ;EACR;EACA,YAAY,UAAU,YAAYA,eAAiB,UAAU,OAAO;EACpE,YAAY,eAAe,cAAc,YAAY,YAAY;CACnE,CAAC;CAGH,MAAM,eAAe;CASrB,OAAO,cALYA,eACjB,GAAG,OAAO,GAAG,EAAE,GAAG,gBAClB,aAAa,aAA0C,GAAG,CAG9B,GAAG,YAAY;AAC/C"}
+{"version":3,"file":"useDictionaryDynamic.mjs","names":["loadDynamicChunk"],"sources":["../../../src/server/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport {\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveDictionaryArgument,\n  resolveQualifiedDynamicContent,\n} from '@intlayer/core/dictionaryManipulator';\nimport type {\n  Dictionary,\n  DictionarySelector,\n} from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n  ProviderVariant,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport {\n  IntlayerServerContext,\n  IntlayerServerVariantContext,\n} from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n// `useLoadDynamic` wraps `react.use`, which may be called in loops /\n// conditionally — aliased to a non-hook name so a collection can load several\n// chunks at once.\nimport { useLoadDynamic as loadDynamicChunk } from './useLoadDynamic';\n\n/**\n * Server-side hook that lazily loads a dictionary and returns its content.\n *\n * The dictionary entry is either a plain dynamic loader map\n * (`locale → loader`) or a qualified one (`locale → qualifierId → loader`,\n * tagged with the qualifier dimension). For qualified maps, only the chunk(s)\n * the selector targets are loaded; the resolution mirrors static mode.\n *\n * If the locale is not provided (directly or through the selector), the server\n * context locale is used.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const A extends DeclaredLocales | DictionarySelector = DeclaredLocales,\n>(\n  dictionaryPromise:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: string,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const contextLocale = getServerContext<LocalesValues>(IntlayerServerContext);\n\n  const { locale: selectorLocale, selector } =\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false'\n      ? parseDictionarySelector<LocalesValues>(\n          // Layers the request's ambient variant under the call-site argument\n          // before the chunk walk, so only the targeted chunk is loaded.\n          resolveDictionaryArgument({\n            localeOrSelector,\n            contextLocale,\n            contextVariant: getServerContext<ProviderVariant>(\n              IntlayerServerVariantContext\n            ),\n            dictionaryKey: String(key),\n          })\n        )\n      : {\n          locale: localeOrSelector as LocalesValues | undefined,\n          selector: undefined,\n        };\n\n  const localeTarget =\n    selectorLocale ??\n    contextLocale ??\n    fallbackLocale ??\n    internationalization.defaultLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    isQualifiedDynamicLoaderMap(dictionaryPromise)\n  ) {\n    return resolveQualifiedDynamicContent({\n      loaderMap: dictionaryPromise,\n      key: String(key),\n      locale: localeTarget,\n      selector,\n      loadChunk: (cacheKey, promise) => loadDynamicChunk(cacheKey, promise),\n      transform: (dictionary) => getDictionary(dictionary, localeTarget),\n    });\n  }\n\n  const plainLoaders = dictionaryPromise as StrictModeLocaleMap<\n    () => Promise<T>\n  >;\n\n  const dictionary = loadDynamicChunk<T>(\n    `${String(key)}.${localeTarget}`,\n    plainLoaders[localeTarget as keyof typeof plainLoaders]?.() as Promise<T>\n  );\n\n  return getDictionary(dictionary, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAwCA,MAAa,wBAIX,mBAGA,KACA,kBACA,mBACG;CACH,MAAM,gBAAgB,iBAAgC,qBAAqB;CAE3E,MAAM,EAAE,QAAQ,gBAAgB,aAC9B,QAAQ,IAAI,iCAAiC,UACzC,wBAGE,0BAA0B;EACxB;EACA;EACA,gBAAgB,iBACd,4BACF;EACA,eAAe,OAAO,GAAG;CAC3B,CAAC,CACH,IACA;EACE,QAAQ;EACR,UAAU;CACZ;CAEN,MAAM,eACJ,kBACA,iBACA,kBACA,qBAAqB;CAEvB,IACE,QAAQ,IAAI,iCAAiC,WAC7C,4BAA4B,iBAAiB,GAE7C,OAAO,+BAA+B;EACpC,WAAW;EACX,KAAK,OAAO,GAAG;EACf,QAAQ;EACR;EACA,YAAY,UAAU,YAAYA,eAAiB,UAAU,OAAO;EACpE,YAAY,eAAe,cAAc,YAAY,YAAY;CACnE,CAAC;CAGH,MAAM,eAAe;CASrB,OAAO,cALYA,eACjB,GAAG,OAAO,GAAG,EAAE,GAAG,gBAClB,aAAa,aAA0C,GAAG,CAG9B,GAAG,YAAY;AAC/C"}

package/dist/esm/server/useIntlayer.mjs

@@ -1,6 +1,7 @@
 import { getIntlayer } from "../getIntlayer.mjs";
 import { getServerContext } from "./serverContext.mjs";
-import { IntlayerServerContext } from "./IntlayerServerProvider.mjs";
+import { IntlayerServerContext, IntlayerServerVariantContext } from "./IntlayerServerProvider.mjs";
+import { resolveDictionaryArgument } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/server/useIntlayer.ts
 /**
@@ -13,10 +14,12 @@ import { IntlayerServerContext } from "./IntlayerServerProvider.mjs";
 */
 const useIntlayer = (key, localeOrSelector, fallbackLocale) => {
 	const contextLocale = getServerContext(IntlayerServerContext) ?? fallbackLocale;
-	if (process.env.INTLAYER_DICTIONARY_SELECTOR !== "false" && typeof localeOrSelector === "object" && localeOrSelector !== null) return getIntlayer(key, {
-		...localeOrSelector,
-		locale: localeOrSelector.locale ?? contextLocale
-	});
+	if (process.env.INTLAYER_DICTIONARY_SELECTOR !== "false") return getIntlayer(key, resolveDictionaryArgument({
+		localeOrSelector,
+		contextLocale,
+		contextVariant: getServerContext(IntlayerServerVariantContext),
+		dictionaryKey: key
+	}));
 	return getIntlayer(key, localeOrSelector ?? contextLocale);
 };
 

package/dist/esm/server/useIntlayer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/server/useIntlayer.ts"],"sourcesContent":["import type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport { IntlayerServerContext } from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n\n/**\n * On the server side, Hook that picking one dictionary by its key and return the content\n *\n * The second argument is either a locale or a selector object\n * (`{ item }`, `{ variant }`, optionally with `locale`).\n *\n * If the locale is not provided, it will use the locale from the server context\n */\nexport const useIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const contextLocale =\n    getServerContext<LocalesValues>(IntlayerServerContext) ?? fallbackLocale;\n\n  if (\n    process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false' &&\n    typeof localeOrSelector === 'object' &&\n    localeOrSelector !== null\n  ) {\n    return getIntlayer(key, {\n      ...localeOrSelector,\n      locale: localeOrSelector.locale ?? contextLocale,\n    } as A);\n  }\n\n  const localeTarget = (localeOrSelector ?? contextLocale) as A;\n\n  return getIntlayer<T, A>(key, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;AAkBA,MAAa,eAIX,KACA,kBACA,mBACG;CACH,MAAM,gBACJ,iBAAgC,qBAAqB,KAAK;CAE5D,IACE,QAAQ,IAAI,iCAAiC,WAC7C,OAAO,qBAAqB,YAC5B,qBAAqB,MAErB,OAAO,YAAY,KAAK;EACtB,GAAG;EACH,QAAQ,iBAAiB,UAAU;CACrC,CAAM;CAKR,OAAO,YAAkB,KAFH,oBAAoB,aAEA;AAC5C"}
+{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/server/useIntlayer.ts"],"sourcesContent":["import { resolveDictionaryArgument } from '@intlayer/core/dictionaryManipulator';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n  ProviderVariant,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport {\n  IntlayerServerContext,\n  IntlayerServerVariantContext,\n} from './IntlayerServerProvider';\nimport { getServerContext } from './serverContext';\n\n/**\n * On the server side, Hook that picking one dictionary by its key and return the content\n *\n * The second argument is either a locale or a selector object\n * (`{ item }`, `{ variant }`, optionally with `locale`).\n *\n * If the locale is not provided, it will use the locale from the server context\n */\nexport const useIntlayer = <\n  const T extends DictionaryKeys,\n  const A extends\n    | DeclaredLocales\n    | DictionarySelectorForKey<T> = DeclaredLocales,\n>(\n  key: T,\n  localeOrSelector?: A,\n  fallbackLocale?: DeclaredLocales\n) => {\n  const contextLocale =\n    getServerContext<LocalesValues>(IntlayerServerContext) ?? fallbackLocale;\n\n  if (process.env.INTLAYER_DICTIONARY_SELECTOR !== 'false') {\n    const contextVariant = getServerContext<ProviderVariant>(\n      IntlayerServerVariantContext\n    );\n\n    return getIntlayer<T, A>(\n      key,\n      resolveDictionaryArgument({\n        localeOrSelector,\n        contextLocale,\n        contextVariant,\n        dictionaryKey: key as string,\n      }) as A\n    );\n  }\n\n  const localeTarget = (localeOrSelector ?? contextLocale) as A;\n\n  return getIntlayer<T, A>(key, localeTarget);\n};\n"],"mappings":";;;;;;;;;;;;;;AAuBA,MAAa,eAMX,KACA,kBACA,mBACG;CACH,MAAM,gBACJ,iBAAgC,qBAAqB,KAAK;CAE5D,IAAI,QAAQ,IAAI,iCAAiC,SAK/C,OAAO,YACL,KACA,0BAA0B;EACxB;EACA;EACA,gBATmB,iBACrB,4BAQe;EACb,eAAe;CACjB,CAAC,CACH;CAKF,OAAO,YAAkB,KAFH,oBAAoB,aAEA;AAC5C"}

package/dist/types/client/IntlayerProvider.d.ts

@@ -1,9 +1,14 @@
-import { LocalesValues } from "@intlayer/types/module_augmentation";
+import { LocalesValues, ProviderVariant } from "@intlayer/types/module_augmentation";
 import { FC, PropsWithChildren } from "react";
 //#region src/client/IntlayerProvider.d.ts
 type IntlayerValue = {
   locale: LocalesValues;
   setLocale: (newLocale: LocalesValues) => void;
+  /**
+   * Ambient variant applied to every dictionary read below the provider, the
+   * same way `locale` is. Overridden per call by an explicit selector.
+   */
+  variant?: ProviderVariant;
   disableEditor?: boolean;
   isCookieEnabled?: boolean;
 };
@@ -25,6 +30,25 @@ type IntlayerProviderProps = PropsWithChildren<{
    * The locale to use. If not provided, it will be detected from storage or configuration.
    */
   locale?: LocalesValues;
+  /**
+   * Ambient variant applied to every dictionary read below this provider — for
+   * a dimension that is fixed for the whole session (tenant, school type, plan
+   * tier…) and that therefore no component should have to pass by hand.
+   *
+   * Accepts three forms:
+   * - `variant="school1"` — one named variant for every key
+   * - `variant={['school1', 'default']}` — an ordered preference chain: the
+   *   first variant the key actually declares wins
+   * - `variant={{ key1: 'school1', key2: ['school1', 'default'], default: 'base' }}`
+   *   — per dictionary key, with `default` covering every key not listed
+   *
+   * A plain object is always read as the per-key map. To pin a structured
+   * variant globally, nest it: `variant={{ default: { id: 'prod_abc' } }}`.
+   *
+   * A call-site selector always wins: `useIntlayer('key', { variant: 'x' })`
+   * replaces this default rather than extending it.
+   */
+  variant?: ProviderVariant;
   /**
    * The default locale to use as a fallback.
    */

package/dist/types/client/IntlayerProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IntlayerProvider.d.ts","names":[],"sources":["../../../src/client/IntlayerProvider.tsx"],"mappings":";;;KAkBK;EACH,QAAQ;EACR,YAAY,WAAW;EACvB;EACA;;;;;cAMW,uCAAqB,QAAA;;;;;;cAWrB;;;;KAKD,wBAAwB;;;;EAIlC,SAAS;;;;EAIT,gBAAgB;;;;EAIhB,aAAa,QAAQ;;;;EAIrB;;;;EAIA;;;;;;;;;;cAWW,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;cA8E5B,kBAAkB,GAAG"}
+{"version":3,"file":"IntlayerProvider.d.ts","names":[],"sources":["../../../src/client/IntlayerProvider.tsx"],"mappings":";;;KAqBK;EACH,QAAQ;EACR,YAAY,WAAW;;;;;EAKvB,UAAU;EACV;EACA;;;;;cAMW,uCAAqB,QAAA;;;;;;cAWrB;;;;KAKD,wBAAwB;;;;EAIlC,SAAS;;;;;;;;;;;;;;;;;;;EAmBT,UAAU;;;;EAIV,gBAAgB;;;;EAIhB,aAAa,QAAQ;;;;EAIrB;;;;EAIA;;;;;;;;;;cAWW,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;cAgF5B,kBAAkB,GAAG"}

package/dist/types/client/useDictionary.d.ts

@@ -1,5 +1,5 @@
 import { IInterpreterPluginState } from "../plugins.js";
-import { DeclaredLocales, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales } from "@intlayer/types/module_augmentation";
 import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup } from "@intlayer/types/dictionary";
 //#region src/client/useDictionary.d.ts
 /**
@@ -7,9 +7,10 @@ import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup } from
  * group) and returns the content.
  *
  * If the locale is not provided (directly or through the selector), it will
- * use the locale from the client context.
+ * use the locale from the client context. The same applies to the variant,
+ * which falls back to the provider's ambient `variant`.
  */
-declare const useDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends LocalesValues | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").ResolveQualifiedDictionaryContent<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
+declare const useDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends DeclaredLocales | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").ResolveQualifiedDictionaryContent<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
 //#endregion
 export { useDictionary };
 //# sourceMappingURL=useDictionary.d.ts.map

package/dist/types/client/useDictionary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionary.d.ts","names":[],"sources":["../../../src/client/useDictionary.ts"],"mappings":";;;;;;;;;;;cAuBa,sBACL,UAAU,aAAa,gCACvB,UACF,gBACA,2BAA2B,KAAK,iBAAe,YAEvC,GAAC,mBACM,2CAAC,+CAAA,kCAAA,GAAA,IAAA,mDAAA,sBAAA"}
+{"version":3,"file":"useDictionary.d.ts","names":[],"sources":["../../../src/client/useDictionary.ts"],"mappings":";;;;;;;;;;;;cAwBa,sBACL,UAAU,aAAa,gCACvB,UACF,kBACA,2BAA2B,KAAK,iBAAe,YAEvC,GAAC,mBACM,2CAAC,+CAAA,kCAAA,GAAA,IAAA,mDAAA,sBAAA"}

package/dist/types/client/useDictionaryDynamic.d.ts

@@ -1,4 +1,4 @@
-import { DictionaryKeys, DictionarySelectorForKey, LocalesValues, StrictModeLocaleMap } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionarySelectorForKey, StrictModeLocaleMap } from "@intlayer/types/module_augmentation";
 import { Dictionary } from "@intlayer/types/dictionary";
 import { QualifiedDynamicLoaderMap } from "@intlayer/core/dictionaryManipulator";
 //#region src/client/useDictionaryDynamic.d.ts
@@ -13,7 +13,7 @@ import { QualifiedDynamicLoaderMap } from "@intlayer/core/dictionaryManipulator"
  * If the locale is not provided (directly or through the selector), the client
  * context locale is used.
  */
-declare const useDictionaryDynamic: <const T extends Dictionary, const K extends DictionaryKeys, const A extends LocalesValues | DictionarySelectorForKey<K> = LocalesValues>(dictionaryPromise: StrictModeLocaleMap<() => Promise<T>> | QualifiedDynamicLoaderMap, key: K, localeOrSelector?: A) => any;
+declare const useDictionaryDynamic: <const T extends Dictionary, const K extends DictionaryKeys, const A extends DeclaredLocales | DictionarySelectorForKey<K> = DeclaredLocales>(dictionaryPromise: StrictModeLocaleMap<() => Promise<T>> | QualifiedDynamicLoaderMap, key: K, localeOrSelector?: A) => any;
 //#endregion
 export { useDictionaryDynamic };
 //# sourceMappingURL=useDictionaryDynamic.d.ts.map

package/dist/types/client/useDictionaryDynamic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionaryDynamic.d.ts","names":[],"sources":["../../../src/client/useDictionaryDynamic.ts"],"mappings":";;;;;;;;;;;;;;;cAmCa,6BACL,UAAU,kBACV,UAAU,sBACV,UAAU,gBAAgB,yBAAyB,KAAK,eAAa,mBAGvE,0BAA0B,QAAQ,MAClC,2BAAyB,KACxB,GAAC,mBACa"}
+{"version":3,"file":"useDictionaryDynamic.d.ts","names":[],"sources":["../../../src/client/useDictionaryDynamic.ts"],"mappings":";;;;;;;;;;;;;;;cAqCa,6BACL,UAAU,kBACV,UAAU,sBACV,UACF,kBACA,yBAAyB,KAAK,iBAAe,mBAG7C,0BAA0B,QAAQ,MAClC,2BAAyB,KACxB,GAAC,mBACa"}

package/dist/types/client/useI18n.d.ts

@@ -1,5 +1,5 @@
 import { DeepTransformContent } from "../plugins.js";
-import { DeclaredLocales, DictionaryKeys, DictionaryRegistryContent, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionaryRegistryContent } from "@intlayer/types/module_augmentation";
 import { ValidDotPathsFor } from "@intlayer/core/transpiler";
 import { GetSubPath } from "@intlayer/types/dictionary";
 //#region src/client/useI18n.d.ts
@@ -20,7 +20,7 @@ import { GetSubPath } from "@intlayer/types/dictionary";
  * const ariaLabel = t('button.ariaLabel').value; // 'Close modal'
  * ```
  */
-declare const useI18n: <T extends DictionaryKeys, L extends LocalesValues = DeclaredLocales>(namespace: T, locale?: L) => <P extends ValidDotPathsFor<T>>(path: P) => GetSubPath<DeepTransformContent<DictionaryRegistryContent<T>>, P>;
+declare const useI18n: <T extends DictionaryKeys, L extends DeclaredLocales = DeclaredLocales>(namespace: T, locale?: L) => <P extends ValidDotPathsFor<T>>(path: P) => GetSubPath<DeepTransformContent<DictionaryRegistryContent<T>>, P>;
 //#endregion
 export { useI18n };
 //# sourceMappingURL=useI18n.d.ts.map

package/dist/types/client/useI18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useI18n.d.ts","names":[],"sources":["../../../src/client/useI18n.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;cAgCa,UACX,UAAU,gBACV,UAAU,gBAAgB,iBAAe,WAE9B,GAAC,SACH,OAkBE,UAAU,iBAAiB,IAAE,MAChC,MAEL,WAAW,qBAAqB,0BAA0B,KAAK"}
+{"version":3,"file":"useI18n.d.ts","names":[],"sources":["../../../src/client/useI18n.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;cA+Ba,UACX,UAAU,gBACV,UAAU,kBAAkB,iBAAe,WAEhC,GAAC,SACH,OAkBE,UAAU,iBAAiB,IAAE,MAChC,MAEL,WAAW,qBAAqB,0BAA0B,KAAK"}

package/dist/types/client/useIntlayer.d.ts

@@ -1,5 +1,5 @@
 import { IInterpreterPluginState } from "../plugins.js";
-import { DeclaredLocales, DictionaryKeys, DictionarySelectorForKey, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionarySelectorForKey } from "@intlayer/types/module_augmentation";
 //#region src/client/useIntlayer.d.ts
 /**
  * Client-side hook that picks one dictionary by its key and returns its content.
@@ -7,8 +7,12 @@ import { DeclaredLocales, DictionaryKeys, DictionarySelectorForKey, LocalesValue
  * The second argument is either a locale or a selector object:
  * - `{ item: 2 }` — collection item (omit `item` to get every item as array)
  * - `{ variant: 'black-friday' }` — named variant (omit for the `default` one)
+ * - `{ variant: ['black-friday', 'promo'] }` — ordered preference chain
  * - `locale` composes with any selector and overrides the context locale
  *
+ * `locale` and `variant` both fall back to the surrounding `IntlayerProvider`
+ * when the call does not pin them.
+ *
  * @param key - The unique key of the dictionary to retrieve.
  * @param localeOrSelector - Optional locale or selector.
  * @returns The dictionary content for the resolved entry and locale.
@@ -25,7 +29,7 @@ import { DeclaredLocales, DictionaryKeys, DictionarySelectorForKey, LocalesValue
  * };
  * ```
  */
-declare const useIntlayer: <const T extends DictionaryKeys, const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales>(key: T, localeOrSelector?: A) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").DictionaryRegistryResult<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
+declare const useIntlayer: <const T extends DictionaryKeys, const A extends DeclaredLocales | DictionarySelectorForKey<T> = DeclaredLocales>(key: T, localeOrSelector?: A) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").DictionaryRegistryResult<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
 //#endregion
 export { useIntlayer };
 //# sourceMappingURL=useIntlayer.d.ts.map

package/dist/types/client/useIntlayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useIntlayer.d.ts","names":[],"sources":["../../../src/client/useIntlayer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;cAqCa,oBACL,UAAU,sBACV,UAAU,gBAAgB,yBAAyB,KAAK,iBAAe,KAExE,GAAC,mBACa,2CAAC,+CAAA,yBAAA,GAAA,IAAA,mDAAA,sBAAA"}
+{"version":3,"file":"useIntlayer.d.ts","names":[],"sources":["../../../src/client/useIntlayer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2Ca,oBACL,UAAU,sBACV,UACF,kBACA,yBAAyB,KAAK,iBAAe,KAE5C,GAAC,mBACa,2CAAC,+CAAA,yBAAA,GAAA,IAAA,mDAAA,sBAAA"}

package/dist/types/getDictionary.d.ts

@@ -1,5 +1,5 @@
 import { DeepTransformContent } from "./plugins.js";
-import { DeclaredLocales, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, ExtractSelectorLocale } from "@intlayer/types/module_augmentation";
 import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup, ResolveQualifiedDictionaryContent } from "@intlayer/types/dictionary";
 //#region src/getDictionary.d.ts
 /**
@@ -7,7 +7,7 @@ import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup, Resol
  * content for the given locale or selector (`{ item }`, `{ variant }`,
  * optionally combined with `locale`).
  */
-declare const getDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends LocalesValues | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A) => DeepTransformContent<ResolveQualifiedDictionaryContent<T, A>, ExtractSelectorLocale<A>>;
+declare const getDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends DeclaredLocales | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A) => DeepTransformContent<ResolveQualifiedDictionaryContent<T, A>, ExtractSelectorLocale<A>>;
 //#endregion
 export { getDictionary };
 //# sourceMappingURL=getDictionary.d.ts.map

package/dist/types/getDictionary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getDictionary.d.ts","names":[],"sources":["../../src/getDictionary.ts"],"mappings":";;;;;;;;;cAmBa,sBACL,UAAU,aAAa,gCACvB,UACF,gBACA,2BAA2B,KAAK,iBAAe,YAEvC,GAAC,mBACM,MAClB,qBACD,kCAAkC,GAAG,IACrC,sBAAsB"}
+{"version":3,"file":"getDictionary.d.ts","names":[],"sources":["../../src/getDictionary.ts"],"mappings":";;;;;;;;;cAmBa,sBACL,UAAU,aAAa,gCACvB,UACF,kBACA,2BAA2B,KAAK,iBAAe,YAEvC,GAAC,mBACM,MAClB,qBACD,kCAAkC,GAAG,IACrC,sBAAsB"}

package/dist/types/getIntlayer.d.ts

@@ -1,12 +1,12 @@
 import { DeepTransformContent } from "./plugins.js";
-import { DeclaredLocales, DictionaryKeys, DictionaryRegistryResult, DictionarySelectorForKey, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionaryRegistryResult, DictionarySelectorForKey, ExtractSelectorLocale } from "@intlayer/types/module_augmentation";
 //#region src/getIntlayer.d.ts
 /**
  * Picks one dictionary by its key and returns its content for the given
  * locale or selector (`{ item }`, `{ variant }`,
  * optionally combined with `locale`).
  */
-declare const getIntlayer: <const T extends DictionaryKeys, const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales>(key: T, localeOrSelector?: A) => DeepTransformContent<DictionaryRegistryResult<T, A>, ExtractSelectorLocale<A>>;
+declare const getIntlayer: <const T extends DictionaryKeys, const A extends DeclaredLocales | DictionarySelectorForKey<T> = DeclaredLocales>(key: T, localeOrSelector?: A) => DeepTransformContent<DictionaryRegistryResult<T, A>, ExtractSelectorLocale<A>>;
 //#endregion
 export { getIntlayer };
 //# sourceMappingURL=getIntlayer.d.ts.map

package/dist/types/getIntlayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getIntlayer.d.ts","names":[],"sources":["../../src/getIntlayer.ts"],"mappings":";;;;;;;;cAgBa,oBACL,UAAU,sBACV,UAAU,gBAAgB,yBAAyB,KAAK,iBAAe,KAExE,GAAC,mBACa,MAClB,qBACD,yBAAyB,GAAG,IAC5B,sBAAsB"}
+{"version":3,"file":"getIntlayer.d.ts","names":[],"sources":["../../src/getIntlayer.ts"],"mappings":";;;;;;;;cAgBa,oBACL,UAAU,sBACV,UACF,kBACA,yBAAyB,KAAK,iBAAe,KAE5C,GAAC,mBACa,MAClB,qBACD,yBAAyB,GAAG,IAC5B,sBAAsB"}

package/dist/types/server/IntlayerServerProvider.d.ts

@@ -1,4 +1,4 @@
-import { LocalesValues } from "@intlayer/types/module_augmentation";
+import { LocalesValues, ProviderVariant } from "@intlayer/types/module_augmentation";
 import { FC, PropsWithChildren } from "react";
 //#region src/server/IntlayerServerProvider.d.ts
 /**
@@ -18,6 +18,26 @@ declare const IntlayerServerContext: FC<PropsWithChildren<{
   };
   _defaultValue: LocalesValues;
 };
+/**
+ * Context that stores the ambient variant on the server side.
+ *
+ * Kept separate from {@link IntlayerServerContext} so the locale context keeps
+ * its plain `LocalesValues` shape for the packages already reading it.
+ */
+declare const IntlayerServerVariantContext: FC<PropsWithChildren<{
+  value?: ProviderVariant;
+}>> & {
+  Provider: FC<PropsWithChildren<{
+    value?: ProviderVariant;
+  }>>;
+  Consumer: FC<PropsWithChildren<{
+    children: (context: ProviderVariant) => import("react").ReactNode;
+  }>>;
+  _storage: () => {
+    value: ProviderVariant;
+  };
+  _defaultValue: ProviderVariant;
+};
 /**
  * Hook that provides the current locale
  */
@@ -28,11 +48,20 @@ declare const useIntlayer: () => LocalesValues;
 declare const locale: LocalesValues;
 type IntlayerServerProviderProps = PropsWithChildren & {
   locale?: LocalesValues;
+  /**
+   * Ambient variant applied to every dictionary read below this provider — for
+   * a dimension resolved once per request (tenant, school type, plan tier…).
+   *
+   * Accepts a name (`'school1'`), an ordered preference chain
+   * (`['school1', 'default']`), or a per-key map
+   * (`{ key1: 'school1', default: 'base' }`). A call-site selector wins.
+   */
+  variant?: ProviderVariant;
 };
 /**
  * Provider that store the current locale on the server side
  */
 declare const IntlayerServerProvider: FC<IntlayerServerProviderProps>;
 //#endregion
-export { IntlayerServerContext, IntlayerServerProvider, IntlayerServerProviderProps, locale, useIntlayer };
+export { IntlayerServerContext, IntlayerServerProvider, IntlayerServerProviderProps, IntlayerServerVariantContext, locale, useIntlayer };
 //# sourceMappingURL=IntlayerServerProvider.d.ts.map

package/dist/types/server/IntlayerServerProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IntlayerServerProvider.d.ts","names":[],"sources":["../../../src/server/IntlayerServerProvider.tsx"],"mappings":";;;;;;cAWa,uBAAqB,GAAA;;;;;;;;;;;;;;;;;cAMrB,mBAAW;;;;cAKX,QAAM;KAEP,8BAA8B;EACxC,SAAS;;;;;cAME,wBAAwB,GAAG"}
+{"version":3,"file":"IntlayerServerProvider.d.ts","names":[],"sources":["../../../src/server/IntlayerServerProvider.tsx"],"mappings":";;;;;;cAca,uBAAqB,GAAA;;;;;;;;;;;;;;;;;;;;cASrB,8BAA4B,GAAA;;;;;;;;;;;;;;;;;cAM5B,mBAAW;;;;cAKX,QAAM;KAEP,8BAA8B;EACxC,SAAS;;;;;;;;;EAST,UAAU;;;;;cAMC,wBAAwB,GAAG"}

package/dist/types/server/useDictionary.d.ts

@@ -1,5 +1,5 @@
 import { IInterpreterPluginState } from "../plugins.js";
-import { DeclaredLocales, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales } from "@intlayer/types/module_augmentation";
 import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup } from "@intlayer/types/dictionary";
 //#region src/server/useDictionary.d.ts
 /**
@@ -9,7 +9,7 @@ import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup } from
  * If the locale is not provided (directly or through the selector), it will
  * use the locale from the server context
  */
-declare const useDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends LocalesValues | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A, fallbackLocale?: DeclaredLocales) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").ResolveQualifiedDictionaryContent<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
+declare const useDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends DeclaredLocales | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A, fallbackLocale?: DeclaredLocales) => import("@intlayer/core/interpreter").DeepTransformContent<import("@intlayer/types").ResolveQualifiedDictionaryContent<T, A>, IInterpreterPluginState, import("@intlayer/types").ExtractSelectorLocale<A>>;
 //#endregion
 export { useDictionary };
 //# sourceMappingURL=useDictionary.d.ts.map