vanilla-intlayer 8.12.4 → 9.0.0-canary.0

package/dist/cjs/client/useDictionary.cjs

@@ -4,50 +4,29 @@ const require_client_installIntlayer = require('./installIntlayer.cjs');
 
 //#region src/client/useDictionary.ts
 /**
-* Get the translated content for a raw dictionary object and optionally
-* subscribe to locale changes via the chainable `.onChange()` method —
-* mirroring the API of `react-intlayer`.
+* Get the content for a raw dictionary (or qualified dictionary group) and
+* optionally subscribe to locale changes via the chainable `.onChange()`
+* method — mirroring the API of `react-intlayer`.
 *
-* Unlike `useIntlayer` (which takes a registered key), this function accepts a
-* dictionary object directly — useful for dictionaries loaded asynchronously
-* or defined inline.
+* The second argument is either a locale or a selector object (`{ item }`,
+* `{ variant }`, `{ id, ...meta }`, optionally combined with `locale`).
 *
-* The function returns the current content **directly** (same shape as
-* `getDictionary(dict)`), plus the `.onChange()` helper:
-*
-* ```ts
-* // React
-* const content = useDictionary(myDict);
-*
-* // Vanilla — identical surface API, opt-in reactivity via .onChange()
-* const content = useDictionary(myDict);
-* const content = useDictionary(myDict).onChange((c) => render(c));
-* ```
-*
-* @param dictionary - The raw dictionary object.
-* @param locale     - Optional locale override.
-* @returns The current translated content with an `.onChange()` method.
-*
-* @example
-* ```ts
-* import myDict from './myDictionary.content';
-* import { installIntlayer, useDictionary } from 'vanilla-intlayer';
-*
-* installIntlayer();
-*
-* const content = useDictionary(myDict).onChange((c) => {
-*   document.querySelector('p').textContent = String(c.greeting);
-* });
-*
-* document.querySelector('p').textContent = String(content.greeting);
-* ```
+* @param dictionary - The raw dictionary (or qualified group) object.
+* @param localeOrSelector - Optional locale or selector.
+* @returns The current content with an `.onChange()` method.
 */
-const useDictionary = (dictionary, locale) => {
+const useDictionary = (dictionary, localeOrSelector) => {
 	const client = require_client_installIntlayer.getIntlayerClient();
-	const content = require_getDictionary.getDictionary(dictionary, locale ?? client.locale);
-	content.onChange = (callback) => {
+	const isSelector = typeof localeOrSelector === "object" && localeOrSelector !== null;
+	const explicitLocale = isSelector ? localeOrSelector.locale : localeOrSelector;
+	const read = (locale) => isSelector ? require_getDictionary.getDictionary(dictionary, {
+		...localeOrSelector,
+		locale
+	}) : require_getDictionary.getDictionary(dictionary, locale);
+	const content = read(explicitLocale ?? client.locale);
+	if (content != null && typeof content === "object") content.onChange = (callback) => {
 		client.subscribe((newLocale) => {
-			callback(require_getDictionary.getDictionary(dictionary, locale ?? newLocale));
+			callback(read(explicitLocale ?? newLocale));
 		});
 		return content;
 	};

package/dist/cjs/client/useDictionary.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionary.cjs","names":["getIntlayerClient","getDictionary"],"sources":["../../../src/client/useDictionary.ts"],"sourcesContent":["import type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\n\nexport type WithOnChange<T> = T & {\n  /**\n   * Subscribe to locale changes. The callback receives the fresh content\n   * whenever the active locale changes. Returns the content object itself\n   * for convenient one-liner patterns:\n   *\n   * ```ts\n   * const content = useDictionary(myDict).onChange((c) => {\n   *   document.querySelector('p')!.textContent = String(c.greeting);\n   * });\n   * ```\n   */\n  onChange: (\n    callback: <T extends Dictionary, L extends LocalesValues>(\n      content: DeepTransformContent<T['content'], L>\n    ) => void\n  ) => WithOnChange<T>;\n};\n\n/**\n * Get the translated content for a raw dictionary object and optionally\n * subscribe to locale changes via the chainable `.onChange()` method —\n * mirroring the API of `react-intlayer`.\n *\n * Unlike `useIntlayer` (which takes a registered key), this function accepts a\n * dictionary object directly — useful for dictionaries loaded asynchronously\n * or defined inline.\n *\n * The function returns the current content **directly** (same shape as\n * `getDictionary(dict)`), plus the `.onChange()` helper:\n *\n * ```ts\n * // React\n * const content = useDictionary(myDict);\n *\n * // Vanilla — identical surface API, opt-in reactivity via .onChange()\n * const content = useDictionary(myDict);\n * const content = useDictionary(myDict).onChange((c) => render(c));\n * ```\n *\n * @param dictionary - The raw dictionary object.\n * @param locale     - Optional locale override.\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import myDict from './myDictionary.content';\n * import { installIntlayer, useDictionary } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * const content = useDictionary(myDict).onChange((c) => {\n *   document.querySelector('p').textContent = String(c.greeting);\n * });\n *\n * document.querySelector('p').textContent = String(content.greeting);\n * ```\n */\nexport const useDictionary = <\n  const T extends Dictionary,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  dictionary: T,\n  locale?: L\n): WithOnChange<DeepTransformContent<T['content'], L>> => {\n  const client = getIntlayerClient();\n  const content = getDictionary(\n    dictionary,\n    (locale ?? client.locale) as L\n  ) as WithOnChange<DeepTransformContent<T['content'], L>>;\n\n  content.onChange = (\n    callback: (content: DeepTransformContent<T['content'], L>) => void\n  ) => {\n    client.subscribe((newLocale) => {\n      callback(getDictionary(dictionary, (locale ?? newLocale) as L));\n    });\n    return content;\n  };\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,iBAIX,YACA,WACwD;CACxD,MAAM,SAASA,kDAAmB;CAClC,MAAM,UAAUC,oCACd,YACC,UAAU,OAAO,OACnB;AAED,SAAQ,YACN,aACG;AACH,SAAO,WAAW,cAAc;AAC9B,YAASA,oCAAc,YAAa,UAAU,UAAgB,CAAC;IAC/D;AACF,SAAO;;AAGT,QAAO"}
+{"version":3,"file":"useDictionary.cjs","names":["getIntlayerClient","getDictionary"],"sources":["../../../src/client/useDictionary.ts"],"sourcesContent":["import type {\n  Dictionary,\n  DictionarySelector,\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 { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\n\nexport type WithOnChange<T> = T & {\n  /**\n   * Subscribe to locale changes. The callback receives the fresh content\n   * whenever the active locale changes. Returns the content object itself\n   * for convenient one-liner patterns:\n   *\n   * ```ts\n   * const content = useDictionary(myDict).onChange((c) => {\n   *   document.querySelector('p')!.textContent = String(c.greeting);\n   * });\n   * ```\n   */\n  onChange: (callback: (content: any) => void) => WithOnChange<T>;\n};\n\n/**\n * Get the content for a raw dictionary (or qualified dictionary group) and\n * optionally subscribe to locale changes via the chainable `.onChange()`\n * method — mirroring the API of `react-intlayer`.\n *\n * The second argument is either a locale or a selector object (`{ item }`,\n * `{ variant }`, `{ id, ...meta }`, optionally combined with `locale`).\n *\n * @param dictionary - The raw dictionary (or qualified group) object.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The current content with an `.onChange()` method.\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): WithOnChange<\n  DeepTransformContent<\n    ResolveQualifiedDictionaryContent<T, A>,\n    ExtractSelectorLocale<A>\n  >\n> => {\n  const client = getIntlayerClient();\n\n  const isSelector =\n    typeof localeOrSelector === 'object' && localeOrSelector !== null;\n  const explicitLocale = isSelector\n    ? (localeOrSelector as DictionarySelector).locale\n    : (localeOrSelector as LocalesValues | undefined);\n\n  const read = (locale: LocalesValues | undefined) =>\n    isSelector\n      ? getDictionary(dictionary, {\n          ...(localeOrSelector as DictionarySelector),\n          locale,\n        } as A)\n      : getDictionary(dictionary, locale as A);\n\n  const content = read(explicitLocale ?? client.locale) as WithOnChange<any>;\n\n  // A selector can resolve to null/array; only objects carry `.onChange`.\n  if (content != null && typeof content === 'object') {\n    content.onChange = (callback) => {\n      client.subscribe((newLocale) => {\n        callback(read(explicitLocale ?? newLocale));\n      });\n      return content;\n    };\n  }\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AA2CA,MAAa,iBAMX,YACA,qBAMG;CACH,MAAM,SAASA,kDAAmB;CAElC,MAAM,aACJ,OAAO,qBAAqB,YAAY,qBAAqB;CAC/D,MAAM,iBAAiB,aAClB,iBAAwC,SACxC;CAEL,MAAM,QAAQ,WACZ,aACIC,oCAAc,YAAY;EACxB,GAAI;EACJ;EACD,CAAM,GACPA,oCAAc,YAAY,OAAY;CAE5C,MAAM,UAAU,KAAK,kBAAkB,OAAO,OAAO;AAGrD,KAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAAS,KAAK,kBAAkB,UAAU,CAAC;IAC3C;AACF,SAAO;;AAIX,QAAO"}

package/dist/cjs/client/useDictionaryDynamic.cjs

@@ -3,12 +3,16 @@ const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
 const require_getDictionary = require('../getDictionary.cjs');
 const require_client_installIntlayer = require('./installIntlayer.cjs');
 let _intlayer_config_built = require("@intlayer/config/built");
+let _intlayer_core_dictionaryManipulator = require("@intlayer/core/dictionaryManipulator");
 
 //#region src/client/useDictionaryDynamic.ts
 /** Simple in-memory cache shared across all calls in the same page. */
 const cache = /* @__PURE__ */ new Map();
 /** Tracks in-flight loads to avoid duplicate fetches. */
 const inflight = /* @__PURE__ */ new Map();
+/** Resolved-content cache for qualified (collection/variant/meta) keys. */
+const qualifiedCache = /* @__PURE__ */ new Map();
+const qualifiedInflight = /* @__PURE__ */ new Map();
 const loadDictionary = (cacheKey, loader) => {
 	if (cache.has(cacheKey)) return Promise.resolve();
 	if (inflight.has(cacheKey)) return inflight.get(cacheKey);
@@ -19,39 +23,78 @@ const loadDictionary = (cacheKey, loader) => {
 	inflight.set(cacheKey, promise);
 	return promise;
 };
+/** Placeholder proxy — safe for any property access while loading. */
+const recursiveProxy = new Proxy(() => {}, {
+	get: (_t, prop) => {
+		if (prop === Symbol.toPrimitive) return () => "";
+		if (prop === "toString") return () => "";
+		if (prop === "valueOf") return () => "";
+		if (prop === "then") return void 0;
+		if (prop === "onChange") return (_cb) => recursiveProxy;
+		return recursiveProxy;
+	},
+	apply: () => recursiveProxy
+});
 /**
-* Dynamically load and transform a locale-keyed dictionary.
+* Dynamically load and transform a dictionary (plain or qualified).
 *
-* Works like `useIntlayer` / `useDictionary` but accepts a locale-keyed map
-* of lazy loaders instead of a pre-imported dictionary. Call it inside your
-* render function — the first call triggers a background fetch and returns
-* placeholder values; when the load completes the client notifies all
-* subscribers (including your render loop) so the render runs again with real
-* content. Subsequent calls for the same locale return immediately from cache.
+* For a qualified loader map (collection / variant / meta record, possibly
+* combined), only the chunk(s) the selector targets are loaded. For a plain
+* loader map, the locale chunk is loaded. The first call returns a placeholder
+* and triggers a background load; the client then notifies subscribers so the
+* render runs again with real content.
 *
-* Locale switches follow the same two-phase pattern: placeholder on first
-* render, real content after the locale bundle loads.
-*
-* @param dictionaryLoaders - Locale-keyed map of `() => Promise<Dictionary>`.
+* @param dictionaryLoaders - Locale-keyed loader map, or a qualified loader map.
 * @param key               - Dictionary key (used for cache namespacing).
-* @param locale            - Optional locale override.
-*
-* @example
-* ```ts
-* import dynDic from '../.intlayer/dynamic_dictionary/app.mjs';
-*
-* const render = () => {
-*   const content = useDictionaryDynamic(dynDic, 'app');
-*   document.querySelector('h1')!.textContent = String(content.title);
-* };
-*
-* render();
-* getIntlayerClient().subscribe(() => render());
-* ```
+* @param localeOrSelector  - Optional locale or selector.
 */
-const useDictionaryDynamic = (dictionaryLoaders, key, locale) => {
+const useDictionaryDynamic = (dictionaryLoaders, key, localeOrSelector) => {
 	const client = require_client_installIntlayer.getIntlayerClient();
-	const currentLocale = locale ?? client.locale ?? _intlayer_config_built.internationalization.defaultLocale;
+	const defaultLocale = _intlayer_config_built.internationalization.defaultLocale;
+	if ((0, _intlayer_core_dictionaryManipulator.isQualifiedDynamicLoaderMap)(dictionaryLoaders)) {
+		const loaderMap = dictionaryLoaders;
+		const { locale: selectorLocale, selector } = (0, _intlayer_core_dictionaryManipulator.parseDictionarySelector)(localeOrSelector);
+		const selectorId = (0, _intlayer_core_dictionaryManipulator.getDictionarySelectorCacheKey)(selector);
+		const buildKey = (locale) => `${String(key)}.${locale}.${selectorId}`;
+		const resolveContent = (locale) => (0, _intlayer_core_dictionaryManipulator.resolveQualifiedDynamicContentAsync)({
+			loaderMap,
+			key: String(key),
+			locale,
+			selector,
+			transform: (dictionary) => require_getDictionary.getDictionary(dictionary, locale)
+		});
+		const currentLocale = selectorLocale ?? client.locale ?? defaultLocale;
+		const cacheKey = buildKey(currentLocale);
+		const attachOnChange = (content) => {
+			if (content != null && typeof content === "object") content.onChange = (callback) => {
+				client.subscribe((newLocale) => {
+					const locale = selectorLocale ?? newLocale;
+					const newKey = buildKey(locale);
+					if (qualifiedCache.has(newKey)) {
+						callback(qualifiedCache.get(newKey));
+						return;
+					}
+					resolveContent(locale).then((resolved) => {
+						qualifiedCache.set(newKey, resolved);
+						callback(resolved);
+					});
+				});
+				return content;
+			};
+			return content;
+		};
+		if (qualifiedCache.has(cacheKey)) return attachOnChange(qualifiedCache.get(cacheKey));
+		if (!qualifiedInflight.has(cacheKey)) {
+			const promise = resolveContent(currentLocale).then((resolved) => {
+				qualifiedCache.set(cacheKey, resolved);
+				qualifiedInflight.delete(cacheKey);
+				client.notify();
+			});
+			qualifiedInflight.set(cacheKey, promise);
+		}
+		return recursiveProxy;
+	}
+	const currentLocale = (typeof localeOrSelector === "string" ? localeOrSelector : void 0) ?? client.locale ?? defaultLocale;
 	const cacheKey = `${String(key)}.${currentLocale}`;
 	const loader = dictionaryLoaders[currentLocale];
 	const cached = cache.get(cacheKey);
@@ -74,17 +117,6 @@ const useDictionaryDynamic = (dictionaryLoaders, key, locale) => {
 	if (loader) loadDictionary(cacheKey, loader).then(() => {
 		client.notify();
 	});
-	const recursiveProxy = new Proxy(() => {}, {
-		get: (_t, prop) => {
-			if (prop === Symbol.toPrimitive) return () => "";
-			if (prop === "toString") return () => "";
-			if (prop === "valueOf") return () => "";
-			if (prop === "then") return void 0;
-			if (prop === "onChange") return (_cb) => recursiveProxy;
-			return recursiveProxy;
-		},
-		apply: () => recursiveProxy
-	});
 	return recursiveProxy;
 };
 

package/dist/cjs/client/useDictionaryDynamic.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useDictionaryDynamic.cjs","names":["getIntlayerClient","internationalization","getDictionary"],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DictionaryKeys,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/** Simple in-memory cache shared across all calls in the same page. */\nconst cache = new Map<string, Dictionary>();\n\n/** Tracks in-flight loads to avoid duplicate fetches. */\nconst inflight = new Map<string, Promise<void>>();\n\nconst loadDictionary = <T extends Dictionary>(\n  cacheKey: string,\n  loader: () => Promise<T>\n): Promise<void> => {\n  if (cache.has(cacheKey)) return Promise.resolve();\n  if (inflight.has(cacheKey)) return inflight.get(cacheKey)!;\n\n  const promise = loader().then((dictionary) => {\n    cache.set(cacheKey, dictionary);\n    inflight.delete(cacheKey);\n  });\n\n  inflight.set(cacheKey, promise);\n  return promise;\n};\n\n/**\n * Dynamically load and transform a locale-keyed dictionary.\n *\n * Works like `useIntlayer` / `useDictionary` but accepts a locale-keyed map\n * of lazy loaders instead of a pre-imported dictionary. Call it inside your\n * render function — the first call triggers a background fetch and returns\n * placeholder values; when the load completes the client notifies all\n * subscribers (including your render loop) so the render runs again with real\n * content. Subsequent calls for the same locale return immediately from cache.\n *\n * Locale switches follow the same two-phase pattern: placeholder on first\n * render, real content after the locale bundle loads.\n *\n * @param dictionaryLoaders - Locale-keyed map of `() => Promise<Dictionary>`.\n * @param key               - Dictionary key (used for cache namespacing).\n * @param locale            - Optional locale override.\n *\n * @example\n * ```ts\n * import dynDic from '../.intlayer/dynamic_dictionary/app.mjs';\n *\n * const render = () => {\n *   const content = useDictionaryDynamic(dynDic, 'app');\n *   document.querySelector('h1')!.textContent = String(content.title);\n * };\n *\n * render();\n * getIntlayerClient().subscribe(() => render());\n * ```\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const L extends LocalesValues = LocalesValues,\n>(\n  dictionaryLoaders: StrictModeLocaleMap<() => Promise<T>>,\n  key: K,\n  locale?: L\n): WithOnChange<DeepTransformContent<T['content'], L>> => {\n  const client = getIntlayerClient();\n  const currentLocale = (locale ??\n    client.locale ??\n    internationalization.defaultLocale) as L;\n\n  const cacheKey = `${String(key)}.${currentLocale}`;\n  const loader = (dictionaryLoaders as Record<string, () => Promise<T>>)[\n    currentLocale\n  ];\n\n  // --- Cache hit: return real content synchronously ---\n  const cached = cache.get(cacheKey);\n  if (cached) {\n    const content = getDictionary(cached as T, currentLocale) as WithOnChange<\n      DeepTransformContent<T['content'], L>\n    >;\n\n    content.onChange = (\n      callback: (content: DeepTransformContent<T['content'], L>) => void\n    ) => {\n      // Re-fire whenever content reloads (locale change → new cache entry).\n      client.subscribe((newLocale) => {\n        const newKey = `${String(key)}.${newLocale}`;\n        const newLoader = (\n          dictionaryLoaders as Record<string, () => Promise<T>>\n        )[newLocale];\n\n        if (!newLoader) return;\n\n        loadDictionary(newKey, newLoader).then(() => {\n          const dict = cache.get(newKey);\n          if (dict) {\n            callback(\n              getDictionary(dict as T, newLocale as L) as DeepTransformContent<\n                T['content'],\n                L\n              >\n            );\n          }\n        });\n      });\n\n      return content;\n    };\n\n    return content;\n  }\n\n  // --- Cache miss: kick off background load, then notify to re-render ---\n  if (loader) {\n    loadDictionary(cacheKey, loader).then(() => {\n      client.notify();\n    });\n  }\n\n  // Placeholder proxy — safe for any property access while loading.\n  const recursiveProxy: any = new Proxy(() => {}, {\n    get: (_t, prop) => {\n      if (prop === Symbol.toPrimitive) return () => '';\n      if (prop === 'toString') return () => '';\n      if (prop === 'valueOf') return () => '';\n      if (prop === 'then') return undefined; // not a Promise\n      if (prop === 'onChange') return (_cb: any) => recursiveProxy;\n      return recursiveProxy;\n    },\n    apply: () => recursiveProxy,\n  });\n\n  return recursiveProxy as WithOnChange<DeepTransformContent<T['content'], L>>;\n};\n"],"mappings":";;;;;;;;AAaA,MAAM,wBAAQ,IAAI,KAAyB;;AAG3C,MAAM,2BAAW,IAAI,KAA4B;AAEjD,MAAM,kBACJ,UACA,WACkB;AAClB,KAAI,MAAM,IAAI,SAAS,CAAE,QAAO,QAAQ,SAAS;AACjD,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO,SAAS,IAAI,SAAS;CAEzD,MAAM,UAAU,QAAQ,CAAC,MAAM,eAAe;AAC5C,QAAM,IAAI,UAAU,WAAW;AAC/B,WAAS,OAAO,SAAS;GACzB;AAEF,UAAS,IAAI,UAAU,QAAQ;AAC/B,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCT,MAAa,wBAKX,mBACA,KACA,WACwD;CACxD,MAAM,SAASA,kDAAmB;CAClC,MAAM,gBAAiB,UACrB,OAAO,UACPC,4CAAqB;CAEvB,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,GAAG;CACnC,MAAM,SAAU,kBACd;CAIF,MAAM,SAAS,MAAM,IAAI,SAAS;AAClC,KAAI,QAAQ;EACV,MAAM,UAAUC,oCAAc,QAAa,cAAc;AAIzD,UAAQ,YACN,aACG;AAEH,UAAO,WAAW,cAAc;IAC9B,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,GAAG;IACjC,MAAM,YACJ,kBACA;AAEF,QAAI,CAAC,UAAW;AAEhB,mBAAe,QAAQ,UAAU,CAAC,WAAW;KAC3C,MAAM,OAAO,MAAM,IAAI,OAAO;AAC9B,SAAI,KACF,UACEA,oCAAc,MAAW,UAAe,CAIzC;MAEH;KACF;AAEF,UAAO;;AAGT,SAAO;;AAIT,KAAI,OACF,gBAAe,UAAU,OAAO,CAAC,WAAW;AAC1C,SAAO,QAAQ;GACf;CAIJ,MAAM,iBAAsB,IAAI,YAAY,IAAI;EAC9C,MAAM,IAAI,SAAS;AACjB,OAAI,SAAS,OAAO,YAAa,cAAa;AAC9C,OAAI,SAAS,WAAY,cAAa;AACtC,OAAI,SAAS,UAAW,cAAa;AACrC,OAAI,SAAS,OAAQ,QAAO;AAC5B,OAAI,SAAS,WAAY,SAAQ,QAAa;AAC9C,UAAO;;EAET,aAAa;EACd,CAAC;AAEF,QAAO"}
+{"version":3,"file":"useDictionaryDynamic.cjs","names":["getIntlayerClient","internationalization","getDictionary"],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport {\n  getDictionarySelectorCacheKey,\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveQualifiedDynamicContentAsync,\n} from '@intlayer/core/dictionaryManipulator';\nimport type {\n  Dictionary,\n  DictionarySelector,\n} from '@intlayer/types/dictionary';\nimport type {\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/** Simple in-memory cache shared across all calls in the same page. */\nconst cache = new Map<string, Dictionary>();\n\n/** Tracks in-flight loads to avoid duplicate fetches. */\nconst inflight = new Map<string, Promise<void>>();\n\n/** Resolved-content cache for qualified (collection/variant/meta) keys. */\nconst qualifiedCache = new Map<string, unknown>();\nconst qualifiedInflight = new Map<string, Promise<void>>();\n\nconst loadDictionary = <T extends Dictionary>(\n  cacheKey: string,\n  loader: () => Promise<T>\n): Promise<void> => {\n  if (cache.has(cacheKey)) return Promise.resolve();\n  if (inflight.has(cacheKey)) return inflight.get(cacheKey)!;\n\n  const promise = loader().then((dictionary) => {\n    cache.set(cacheKey, dictionary);\n    inflight.delete(cacheKey);\n  });\n\n  inflight.set(cacheKey, promise);\n  return promise;\n};\n\n/** Placeholder proxy — safe for any property access while loading. */\nconst recursiveProxy: any = new Proxy(() => {}, {\n  get: (_t, prop) => {\n    if (prop === Symbol.toPrimitive) return () => '';\n    if (prop === 'toString') return () => '';\n    if (prop === 'valueOf') return () => '';\n    if (prop === 'then') return undefined; // not a Promise\n    if (prop === 'onChange') return (_cb: any) => recursiveProxy;\n    return recursiveProxy;\n  },\n  apply: () => recursiveProxy,\n});\n\n/**\n * Dynamically load and transform a dictionary (plain or qualified).\n *\n * For a qualified loader map (collection / variant / meta record, possibly\n * combined), only the chunk(s) the selector targets are loaded. For a plain\n * loader map, the locale chunk is loaded. The first call returns a placeholder\n * and triggers a background load; the client then notifies subscribers so the\n * render runs again with real content.\n *\n * @param dictionaryLoaders - Locale-keyed loader map, or a qualified loader map.\n * @param key               - Dictionary key (used for cache namespacing).\n * @param localeOrSelector  - Optional locale or selector.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<K> = LocalesValues,\n>(\n  dictionaryLoaders:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: K,\n  localeOrSelector?: A\n): WithOnChange<DeepTransformContent<T['content']>> => {\n  const client = getIntlayerClient();\n  const defaultLocale = internationalization.defaultLocale;\n\n  // --- Qualified loader map (collection / variant / meta record) ---\n  if (isQualifiedDynamicLoaderMap(dictionaryLoaders)) {\n    const loaderMap = dictionaryLoaders;\n    const { locale: selectorLocale, selector } =\n      parseDictionarySelector<LocalesValues>(localeOrSelector);\n    const selectorId = getDictionarySelectorCacheKey(selector);\n\n    const buildKey = (locale: string) =>\n      `${String(key)}.${locale}.${selectorId}`;\n    const resolveContent = (locale: LocalesValues) =>\n      resolveQualifiedDynamicContentAsync({\n        loaderMap,\n        key: String(key),\n        locale,\n        selector,\n        transform: (dictionary) => getDictionary(dictionary, locale),\n      });\n\n    const currentLocale = (selectorLocale ??\n      client.locale ??\n      defaultLocale) as LocalesValues;\n    const cacheKey = buildKey(currentLocale);\n\n    const attachOnChange = (content: any) => {\n      if (content != null && typeof content === 'object') {\n        content.onChange = (callback: (c: any) => void) => {\n          client.subscribe((newLocale) => {\n            const locale = (selectorLocale ?? newLocale) as LocalesValues;\n            const newKey = buildKey(locale);\n\n            if (qualifiedCache.has(newKey)) {\n              callback(qualifiedCache.get(newKey));\n              return;\n            }\n\n            resolveContent(locale).then((resolved) => {\n              qualifiedCache.set(newKey, resolved);\n              callback(resolved);\n            });\n          });\n          return content;\n        };\n      }\n      return content;\n    };\n\n    if (qualifiedCache.has(cacheKey)) {\n      return attachOnChange(qualifiedCache.get(cacheKey)) as any;\n    }\n\n    if (!qualifiedInflight.has(cacheKey)) {\n      const promise = resolveContent(currentLocale).then((resolved) => {\n        qualifiedCache.set(cacheKey, resolved);\n        qualifiedInflight.delete(cacheKey);\n        client.notify();\n      });\n      qualifiedInflight.set(cacheKey, promise);\n    }\n\n    return recursiveProxy;\n  }\n\n  // --- Plain locale-keyed loader map ---\n  const locale =\n    typeof localeOrSelector === 'string'\n      ? (localeOrSelector as LocalesValues)\n      : undefined;\n  const currentLocale = (locale ?? client.locale ?? defaultLocale) as A;\n\n  const cacheKey = `${String(key)}.${currentLocale}`;\n  const loader = (dictionaryLoaders as Record<string, () => Promise<T>>)[\n    currentLocale as string\n  ];\n\n  // --- Cache hit: return real content synchronously ---\n  const cached = cache.get(cacheKey);\n  if (cached) {\n    const content = getDictionary(cached, currentLocale) as WithOnChange<\n      DeepTransformContent<T['content']>\n    >;\n\n    content.onChange = (callback) => {\n      // Re-fire whenever content reloads (locale change → new cache entry).\n      client.subscribe((newLocale) => {\n        const newKey = `${String(key)}.${newLocale}`;\n        const newLoader = (\n          dictionaryLoaders as Record<string, () => Promise<T>>\n        )[newLocale];\n\n        if (!newLoader) return;\n\n        loadDictionary(newKey, newLoader).then(() => {\n          const dict = cache.get(newKey);\n          if (dict) {\n            callback(getDictionary(dict, newLocale as A) as any);\n          }\n        });\n      });\n\n      return content;\n    };\n\n    return content;\n  }\n\n  // --- Cache miss: kick off background load, then notify to re-render ---\n  if (loader) {\n    loadDictionary(cacheKey, loader).then(() => {\n      client.notify();\n    });\n  }\n\n  return recursiveProxy;\n};\n"],"mappings":";;;;;;;;;AAwBA,MAAM,wBAAQ,IAAI,KAAyB;;AAG3C,MAAM,2BAAW,IAAI,KAA4B;;AAGjD,MAAM,iCAAiB,IAAI,KAAsB;AACjD,MAAM,oCAAoB,IAAI,KAA4B;AAE1D,MAAM,kBACJ,UACA,WACkB;AAClB,KAAI,MAAM,IAAI,SAAS,CAAE,QAAO,QAAQ,SAAS;AACjD,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO,SAAS,IAAI,SAAS;CAEzD,MAAM,UAAU,QAAQ,CAAC,MAAM,eAAe;AAC5C,QAAM,IAAI,UAAU,WAAW;AAC/B,WAAS,OAAO,SAAS;GACzB;AAEF,UAAS,IAAI,UAAU,QAAQ;AAC/B,QAAO;;;AAIT,MAAM,iBAAsB,IAAI,YAAY,IAAI;CAC9C,MAAM,IAAI,SAAS;AACjB,MAAI,SAAS,OAAO,YAAa,cAAa;AAC9C,MAAI,SAAS,WAAY,cAAa;AACtC,MAAI,SAAS,UAAW,cAAa;AACrC,MAAI,SAAS,OAAQ,QAAO;AAC5B,MAAI,SAAS,WAAY,SAAQ,QAAa;AAC9C,SAAO;;CAET,aAAa;CACd,CAAC;;;;;;;;;;;;;;AAeF,MAAa,wBAKX,mBAGA,KACA,qBACqD;CACrD,MAAM,SAASA,kDAAmB;CAClC,MAAM,gBAAgBC,4CAAqB;AAG3C,2EAAgC,kBAAkB,EAAE;EAClD,MAAM,YAAY;EAClB,MAAM,EAAE,QAAQ,gBAAgB,+EACS,iBAAiB;EAC1D,MAAM,qFAA2C,SAAS;EAE1D,MAAM,YAAY,WAChB,GAAG,OAAO,IAAI,CAAC,GAAG,OAAO,GAAG;EAC9B,MAAM,kBAAkB,yFACc;GAClC;GACA,KAAK,OAAO,IAAI;GAChB;GACA;GACA,YAAY,eAAeC,oCAAc,YAAY,OAAO;GAC7D,CAAC;EAEJ,MAAM,gBAAiB,kBACrB,OAAO,UACP;EACF,MAAM,WAAW,SAAS,cAAc;EAExC,MAAM,kBAAkB,YAAiB;AACvC,OAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAA+B;AACjD,WAAO,WAAW,cAAc;KAC9B,MAAM,SAAU,kBAAkB;KAClC,MAAM,SAAS,SAAS,OAAO;AAE/B,SAAI,eAAe,IAAI,OAAO,EAAE;AAC9B,eAAS,eAAe,IAAI,OAAO,CAAC;AACpC;;AAGF,oBAAe,OAAO,CAAC,MAAM,aAAa;AACxC,qBAAe,IAAI,QAAQ,SAAS;AACpC,eAAS,SAAS;OAClB;MACF;AACF,WAAO;;AAGX,UAAO;;AAGT,MAAI,eAAe,IAAI,SAAS,CAC9B,QAAO,eAAe,eAAe,IAAI,SAAS,CAAC;AAGrD,MAAI,CAAC,kBAAkB,IAAI,SAAS,EAAE;GACpC,MAAM,UAAU,eAAe,cAAc,CAAC,MAAM,aAAa;AAC/D,mBAAe,IAAI,UAAU,SAAS;AACtC,sBAAkB,OAAO,SAAS;AAClC,WAAO,QAAQ;KACf;AACF,qBAAkB,IAAI,UAAU,QAAQ;;AAG1C,SAAO;;CAQT,MAAM,iBAHJ,OAAO,qBAAqB,WACvB,mBACD,WAC2B,OAAO,UAAU;CAElD,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,GAAG;CACnC,MAAM,SAAU,kBACd;CAIF,MAAM,SAAS,MAAM,IAAI,SAAS;AAClC,KAAI,QAAQ;EACV,MAAM,UAAUA,oCAAc,QAAQ,cAAc;AAIpD,UAAQ,YAAY,aAAa;AAE/B,UAAO,WAAW,cAAc;IAC9B,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,GAAG;IACjC,MAAM,YACJ,kBACA;AAEF,QAAI,CAAC,UAAW;AAEhB,mBAAe,QAAQ,UAAU,CAAC,WAAW;KAC3C,MAAM,OAAO,MAAM,IAAI,OAAO;AAC9B,SAAI,KACF,UAASA,oCAAc,MAAM,UAAe,CAAQ;MAEtD;KACF;AAEF,UAAO;;AAGT,SAAO;;AAIT,KAAI,OACF,gBAAe,UAAU,OAAO,CAAC,WAAW;AAC1C,SAAO,QAAQ;GACf;AAGJ,QAAO"}

package/dist/cjs/client/useIntlayer.cjs

@@ -8,28 +8,17 @@ const require_client_installIntlayer = require('./installIntlayer.cjs');
 * locale changes via the chainable `.onChange()` method — mirroring the API
 * of `react-intlayer`'s `useIntlayer`.
 *
-* Unlike React (where the hook system automatically re-runs on re-render),
-* vanilla JS has no component lifecycle. The `.onChange()` callback is the
-* explicit equivalent: it is called with fresh content whenever the active
-* locale changes. Use it to patch your DOM or trigger a full re-render.
+* 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)
+* - `{ id: 'prod_abc', ...metaFields }` — meta record
+* - `locale` composes with any selector and overrides the current locale
 *
 * The function returns the current content **directly** (same shape as
-* `getIntlayer(key)`), plus the `.onChange()` helper:
+* `getIntlayer(key)`), plus the `.onChange()` helper.
 *
-* ```ts
-* // React
-* const content = useIntlayer('app');
-*
-* // Vanilla — identical surface API, opt-in reactivity via .onChange()
-* const content = useIntlayer('app');
-* const content = useIntlayer('app').onChange((c) => render(c));
-* ```
-*
-* For cleanup (e.g. Vite HMR), subscribe via `getIntlayerClient().subscribe()`
-* and hold the returned unsubscribe function.
-*
-* @param key    - Dictionary key registered in your intlayer content files.
-* @param locale - Optional locale override (defaults to the current app locale).
+* @param key - Dictionary key registered in your intlayer content files.
+* @param localeOrSelector - Optional locale or selector.
 * @returns The current translated content with an `.onChange()` method.
 *
 * @example
@@ -38,22 +27,22 @@ const require_client_installIntlayer = require('./installIntlayer.cjs');
 *
 * installIntlayer();
 *
-* // Static read (no subscription)
 * const content = useIntlayer('homepage');
-* document.querySelector('h1').textContent = String(content.title);
-*
-* // Reactive read — onChange is called on every locale change
-* useIntlayer('homepage').onChange((c) => {
-*   document.querySelector('h1').textContent = String(c.title);
-* });
+* const faq2 = useIntlayer('faq', { item: 2 });
 * ```
 */
-const useIntlayer = (key, locale) => {
+const useIntlayer = (key, localeOrSelector) => {
 	const client = require_client_installIntlayer.getIntlayerClient();
-	const content = require_getIntlayer.getIntlayer(key, locale ?? client.locale);
-	content.onChange = (callback) => {
+	const isSelector = typeof localeOrSelector === "object" && localeOrSelector !== null;
+	const explicitLocale = isSelector ? localeOrSelector.locale : localeOrSelector;
+	const read = (locale) => isSelector ? require_getIntlayer.getIntlayer(key, {
+		...localeOrSelector,
+		locale
+	}) : require_getIntlayer.getIntlayer(key, locale);
+	const content = read(explicitLocale ?? client.locale);
+	if (content != null && typeof content === "object") content.onChange = (callback) => {
 		client.subscribe((newLocale) => {
-			callback(require_getIntlayer.getIntlayer(key, locale ?? newLocale));
+			callback(read(explicitLocale ?? newLocale));
 		});
 		return content;
 	};

package/dist/cjs/client/useIntlayer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useIntlayer.cjs","names":["getIntlayerClient","getIntlayer"],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["import type {\n  DictionaryKeys,\n  DictionaryRegistryContent,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/**\n * Get the translated content for the given key and optionally subscribe to\n * locale changes via the chainable `.onChange()` method — mirroring the API\n * of `react-intlayer`'s `useIntlayer`.\n *\n * Unlike React (where the hook system automatically re-runs on re-render),\n * vanilla JS has no component lifecycle. The `.onChange()` callback is the\n * explicit equivalent: it is called with fresh content whenever the active\n * locale changes. Use it to patch your DOM or trigger a full re-render.\n *\n * The function returns the current content **directly** (same shape as\n * `getIntlayer(key)`), plus the `.onChange()` helper:\n *\n * ```ts\n * // React\n * const content = useIntlayer('app');\n *\n * // Vanilla — identical surface API, opt-in reactivity via .onChange()\n * const content = useIntlayer('app');\n * const content = useIntlayer('app').onChange((c) => render(c));\n * ```\n *\n * For cleanup (e.g. Vite HMR), subscribe via `getIntlayerClient().subscribe()`\n * and hold the returned unsubscribe function.\n *\n * @param key    - Dictionary key registered in your intlayer content files.\n * @param locale - Optional locale override (defaults to the current app locale).\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import { installIntlayer, useIntlayer } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * // Static read (no subscription)\n * const content = useIntlayer('homepage');\n * document.querySelector('h1').textContent = String(content.title);\n *\n * // Reactive read — onChange is called on every locale change\n * useIntlayer('homepage').onChange((c) => {\n *   document.querySelector('h1').textContent = String(c.title);\n * });\n * ```\n */\nexport const useIntlayer = <const T extends DictionaryKeys>(\n  key: T,\n  locale?: LocalesValues\n): WithOnChange<DeepTransformContent<DictionaryRegistryContent<T>>> => {\n  const client = getIntlayerClient();\n  const content = getIntlayer(key, locale ?? client.locale) as WithOnChange<\n    DeepTransformContent<DictionaryRegistryContent<T>>\n  >;\n\n  content.onChange = (callback) => {\n    client.subscribe((newLocale) => {\n      callback(getIntlayer(key, (locale ?? newLocale) as typeof locale));\n    });\n    return content;\n  };\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,MAAa,eACX,KACA,WACqE;CACrE,MAAM,SAASA,kDAAmB;CAClC,MAAM,UAAUC,gCAAY,KAAK,UAAU,OAAO,OAAO;AAIzD,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAASA,gCAAY,KAAM,UAAU,UAA4B,CAAC;IAClE;AACF,SAAO;;AAGT,QAAO"}
+{"version":3,"file":"useIntlayer.cjs","names":["getIntlayerClient","getIntlayer"],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["import type { DictionarySelector } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryResult,\n  DictionarySelectorForKey,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/**\n * Get the translated content for the given key and optionally subscribe to\n * locale changes via the chainable `.onChange()` method — mirroring the API\n * of `react-intlayer`'s `useIntlayer`.\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 * - `{ id: 'prod_abc', ...metaFields }` — meta record\n * - `locale` composes with any selector and overrides the current locale\n *\n * The function returns the current content **directly** (same shape as\n * `getIntlayer(key)`), plus the `.onChange()` helper.\n *\n * @param key - Dictionary key registered in your intlayer content files.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import { installIntlayer, useIntlayer } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * const content = useIntlayer('homepage');\n * const faq2 = useIntlayer('faq', { item: 2 });\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): WithOnChange<\n  DeepTransformContent<DictionaryRegistryResult<T, A>, ExtractSelectorLocale<A>>\n> => {\n  const client = getIntlayerClient();\n\n  const isSelector =\n    typeof localeOrSelector === 'object' && localeOrSelector !== null;\n  const explicitLocale = isSelector\n    ? (localeOrSelector as DictionarySelector).locale\n    : (localeOrSelector as LocalesValues | undefined);\n\n  const read = (locale: LocalesValues | undefined) =>\n    isSelector\n      ? getIntlayer(key, {\n          ...(localeOrSelector as DictionarySelector),\n          locale,\n        } as A)\n      : getIntlayer(key, locale as A);\n\n  const content = read(explicitLocale ?? client.locale) as WithOnChange<any>;\n\n  // A selector can resolve to null/array; only objects carry `.onChange`.\n  if (content != null && typeof content === 'object') {\n    content.onChange = (callback) => {\n      client.subscribe((newLocale) => {\n        callback(read(explicitLocale ?? newLocale));\n      });\n      return content;\n    };\n  }\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAa,eAIX,KACA,qBAGG;CACH,MAAM,SAASA,kDAAmB;CAElC,MAAM,aACJ,OAAO,qBAAqB,YAAY,qBAAqB;CAC/D,MAAM,iBAAiB,aAClB,iBAAwC,SACxC;CAEL,MAAM,QAAQ,WACZ,aACIC,gCAAY,KAAK;EACf,GAAI;EACJ;EACD,CAAM,GACPA,gCAAY,KAAK,OAAY;CAEnC,MAAM,UAAU,KAAK,kBAAkB,OAAO,OAAO;AAGrD,KAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAAS,KAAK,kBAAkB,UAAU,CAAC;IAC3C;AACF,SAAO;;AAIX,QAAO"}

package/dist/cjs/getDictionary.cjs

@@ -4,7 +4,14 @@ const require_plugins = require('./plugins.cjs');
 let _intlayer_core_interpreter = require("@intlayer/core/interpreter");
 
 //#region src/getDictionary.ts
-const getDictionary = (dictionary, locale) => (0, _intlayer_core_interpreter.getDictionary)(dictionary, locale, require_plugins.getPlugins(locale));
+/**
+* Transforms a dictionary (or qualified dictionary group) and returns its
+* content for the given locale or selector (`{ item }`, `{ variant }`,
+* `{ id, ...meta }`, optionally combined with `locale`).
+*/
+const getDictionary = (dictionary, localeOrSelector) => {
+	return (0, _intlayer_core_interpreter.getDictionary)(dictionary, localeOrSelector, require_plugins.getPlugins(typeof localeOrSelector === "object" && localeOrSelector !== null ? localeOrSelector.locale : localeOrSelector));
+};
 
 //#endregion
 exports.getDictionary = getDictionary;

package/dist/cjs/getDictionary.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"getDictionary.cjs","names":["getPlugins"],"sources":["../../src/getDictionary.ts"],"sourcesContent":["import { getDictionary as getDictionaryCore } from '@intlayer/core/interpreter';\nimport type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\nexport const getDictionary = <\n  const T extends Dictionary,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  dictionary: T,\n  locale?: L\n): DeepTransformContent<T['content'], L> =>\n  getDictionaryCore(dictionary, locale, getPlugins(locale)) as any;\n"],"mappings":";;;;;;AAQA,MAAa,iBAIX,YACA,yDAEkB,YAAY,QAAQA,2BAAW,OAAO,CAAC"}
+{"version":3,"file":"getDictionary.cjs","names":["getPlugins"],"sources":["../../src/getDictionary.ts"],"sourcesContent":["import { getDictionary as getDictionaryCore } from '@intlayer/core/interpreter';\nimport type {\n  Dictionary,\n  DictionarySelector,\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 * `{ id, ...meta }`, 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":";;;;;;;;;;;AAoBA,MAAa,iBAMX,YACA,qBAIG;AAOH,sDACE,YACA,kBACAA,2BARA,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,iBAMc,CACnB"}

package/dist/cjs/getIntlayer.cjs

@@ -4,7 +4,14 @@ const require_plugins = require('./plugins.cjs');
 let _intlayer_core_interpreter = require("@intlayer/core/interpreter");
 
 //#region src/getIntlayer.ts
-const getIntlayer = (key, locale) => (0, _intlayer_core_interpreter.getIntlayer)(key, locale, require_plugins.getPlugins(locale));
+/**
+* Picks one dictionary by its key and returns its content for the given
+* locale or selector (`{ item }`, `{ variant }`, `{ id, ...meta }`,
+* optionally combined with `locale`).
+*/
+const getIntlayer = (key, localeOrSelector) => {
+	return (0, _intlayer_core_interpreter.getIntlayer)(key, localeOrSelector, require_plugins.getPlugins(typeof localeOrSelector === "object" && localeOrSelector !== null ? localeOrSelector.locale : localeOrSelector));
+};
 
 //#endregion
 exports.getIntlayer = getIntlayer;

package/dist/cjs/getIntlayer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"getIntlayer.cjs","names":["getPlugins"],"sources":["../../src/getIntlayer.ts"],"sourcesContent":["import { getIntlayer as getIntlayerCore } from '@intlayer/core/interpreter';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryContent,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\nexport const getIntlayer = <\n  const T extends DictionaryKeys,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  key: T,\n  locale?: L\n): DeepTransformContent<DictionaryRegistryContent<T>, L> =>\n  getIntlayerCore(key, locale, getPlugins(locale)) as any;\n"],"mappings":";;;;;;AASA,MAAa,eAIX,KACA,uDAEgB,KAAK,QAAQA,2BAAW,OAAO,CAAC"}
+{"version":3,"file":"getIntlayer.cjs","names":["getPlugins"],"sources":["../../src/getIntlayer.ts"],"sourcesContent":["import { getIntlayer as getIntlayerCore } from '@intlayer/core/interpreter';\nimport type { DictionarySelector } from '@intlayer/types/dictionary';\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 }`, `{ id, ...meta }`,\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":";;;;;;;;;;;AAiBA,MAAa,eAIX,KACA,qBAIG;AAOH,oDAAuB,KAAK,kBAAkBA,2BAL5C,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,iBAG0D,CAAC"}

package/dist/esm/client/useDictionary.mjs

@@ -3,50 +3,29 @@ import { getIntlayerClient } from "./installIntlayer.mjs";
 
 //#region src/client/useDictionary.ts
 /**
-* Get the translated content for a raw dictionary object and optionally
-* subscribe to locale changes via the chainable `.onChange()` method —
-* mirroring the API of `react-intlayer`.
+* Get the content for a raw dictionary (or qualified dictionary group) and
+* optionally subscribe to locale changes via the chainable `.onChange()`
+* method — mirroring the API of `react-intlayer`.
 *
-* Unlike `useIntlayer` (which takes a registered key), this function accepts a
-* dictionary object directly — useful for dictionaries loaded asynchronously
-* or defined inline.
+* The second argument is either a locale or a selector object (`{ item }`,
+* `{ variant }`, `{ id, ...meta }`, optionally combined with `locale`).
 *
-* The function returns the current content **directly** (same shape as
-* `getDictionary(dict)`), plus the `.onChange()` helper:
-*
-* ```ts
-* // React
-* const content = useDictionary(myDict);
-*
-* // Vanilla — identical surface API, opt-in reactivity via .onChange()
-* const content = useDictionary(myDict);
-* const content = useDictionary(myDict).onChange((c) => render(c));
-* ```
-*
-* @param dictionary - The raw dictionary object.
-* @param locale     - Optional locale override.
-* @returns The current translated content with an `.onChange()` method.
-*
-* @example
-* ```ts
-* import myDict from './myDictionary.content';
-* import { installIntlayer, useDictionary } from 'vanilla-intlayer';
-*
-* installIntlayer();
-*
-* const content = useDictionary(myDict).onChange((c) => {
-*   document.querySelector('p').textContent = String(c.greeting);
-* });
-*
-* document.querySelector('p').textContent = String(content.greeting);
-* ```
+* @param dictionary - The raw dictionary (or qualified group) object.
+* @param localeOrSelector - Optional locale or selector.
+* @returns The current content with an `.onChange()` method.
 */
-const useDictionary = (dictionary, locale) => {
+const useDictionary = (dictionary, localeOrSelector) => {
 	const client = getIntlayerClient();
-	const content = getDictionary(dictionary, locale ?? client.locale);
-	content.onChange = (callback) => {
+	const isSelector = typeof localeOrSelector === "object" && localeOrSelector !== null;
+	const explicitLocale = isSelector ? localeOrSelector.locale : localeOrSelector;
+	const read = (locale) => isSelector ? getDictionary(dictionary, {
+		...localeOrSelector,
+		locale
+	}) : getDictionary(dictionary, locale);
+	const content = read(explicitLocale ?? client.locale);
+	if (content != null && typeof content === "object") content.onChange = (callback) => {
 		client.subscribe((newLocale) => {
-			callback(getDictionary(dictionary, locale ?? newLocale));
+			callback(read(explicitLocale ?? newLocale));
 		});
 		return content;
 	};

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

@@ -1 +1 @@
-{"version":3,"file":"useDictionary.mjs","names":[],"sources":["../../../src/client/useDictionary.ts"],"sourcesContent":["import type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\n\nexport type WithOnChange<T> = T & {\n  /**\n   * Subscribe to locale changes. The callback receives the fresh content\n   * whenever the active locale changes. Returns the content object itself\n   * for convenient one-liner patterns:\n   *\n   * ```ts\n   * const content = useDictionary(myDict).onChange((c) => {\n   *   document.querySelector('p')!.textContent = String(c.greeting);\n   * });\n   * ```\n   */\n  onChange: (\n    callback: <T extends Dictionary, L extends LocalesValues>(\n      content: DeepTransformContent<T['content'], L>\n    ) => void\n  ) => WithOnChange<T>;\n};\n\n/**\n * Get the translated content for a raw dictionary object and optionally\n * subscribe to locale changes via the chainable `.onChange()` method —\n * mirroring the API of `react-intlayer`.\n *\n * Unlike `useIntlayer` (which takes a registered key), this function accepts a\n * dictionary object directly — useful for dictionaries loaded asynchronously\n * or defined inline.\n *\n * The function returns the current content **directly** (same shape as\n * `getDictionary(dict)`), plus the `.onChange()` helper:\n *\n * ```ts\n * // React\n * const content = useDictionary(myDict);\n *\n * // Vanilla — identical surface API, opt-in reactivity via .onChange()\n * const content = useDictionary(myDict);\n * const content = useDictionary(myDict).onChange((c) => render(c));\n * ```\n *\n * @param dictionary - The raw dictionary object.\n * @param locale     - Optional locale override.\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import myDict from './myDictionary.content';\n * import { installIntlayer, useDictionary } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * const content = useDictionary(myDict).onChange((c) => {\n *   document.querySelector('p').textContent = String(c.greeting);\n * });\n *\n * document.querySelector('p').textContent = String(content.greeting);\n * ```\n */\nexport const useDictionary = <\n  const T extends Dictionary,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  dictionary: T,\n  locale?: L\n): WithOnChange<DeepTransformContent<T['content'], L>> => {\n  const client = getIntlayerClient();\n  const content = getDictionary(\n    dictionary,\n    (locale ?? client.locale) as L\n  ) as WithOnChange<DeepTransformContent<T['content'], L>>;\n\n  content.onChange = (\n    callback: (content: DeepTransformContent<T['content'], L>) => void\n  ) => {\n    client.subscribe((newLocale) => {\n      callback(getDictionary(dictionary, (locale ?? newLocale) as L));\n    });\n    return content;\n  };\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,iBAIX,YACA,WACwD;CACxD,MAAM,SAAS,mBAAmB;CAClC,MAAM,UAAU,cACd,YACC,UAAU,OAAO,OACnB;AAED,SAAQ,YACN,aACG;AACH,SAAO,WAAW,cAAc;AAC9B,YAAS,cAAc,YAAa,UAAU,UAAgB,CAAC;IAC/D;AACF,SAAO;;AAGT,QAAO"}
+{"version":3,"file":"useDictionary.mjs","names":[],"sources":["../../../src/client/useDictionary.ts"],"sourcesContent":["import type {\n  Dictionary,\n  DictionarySelector,\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 { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\n\nexport type WithOnChange<T> = T & {\n  /**\n   * Subscribe to locale changes. The callback receives the fresh content\n   * whenever the active locale changes. Returns the content object itself\n   * for convenient one-liner patterns:\n   *\n   * ```ts\n   * const content = useDictionary(myDict).onChange((c) => {\n   *   document.querySelector('p')!.textContent = String(c.greeting);\n   * });\n   * ```\n   */\n  onChange: (callback: (content: any) => void) => WithOnChange<T>;\n};\n\n/**\n * Get the content for a raw dictionary (or qualified dictionary group) and\n * optionally subscribe to locale changes via the chainable `.onChange()`\n * method — mirroring the API of `react-intlayer`.\n *\n * The second argument is either a locale or a selector object (`{ item }`,\n * `{ variant }`, `{ id, ...meta }`, optionally combined with `locale`).\n *\n * @param dictionary - The raw dictionary (or qualified group) object.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The current content with an `.onChange()` method.\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): WithOnChange<\n  DeepTransformContent<\n    ResolveQualifiedDictionaryContent<T, A>,\n    ExtractSelectorLocale<A>\n  >\n> => {\n  const client = getIntlayerClient();\n\n  const isSelector =\n    typeof localeOrSelector === 'object' && localeOrSelector !== null;\n  const explicitLocale = isSelector\n    ? (localeOrSelector as DictionarySelector).locale\n    : (localeOrSelector as LocalesValues | undefined);\n\n  const read = (locale: LocalesValues | undefined) =>\n    isSelector\n      ? getDictionary(dictionary, {\n          ...(localeOrSelector as DictionarySelector),\n          locale,\n        } as A)\n      : getDictionary(dictionary, locale as A);\n\n  const content = read(explicitLocale ?? client.locale) as WithOnChange<any>;\n\n  // A selector can resolve to null/array; only objects carry `.onChange`.\n  if (content != null && typeof content === 'object') {\n    content.onChange = (callback) => {\n      client.subscribe((newLocale) => {\n        callback(read(explicitLocale ?? newLocale));\n      });\n      return content;\n    };\n  }\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;AA2CA,MAAa,iBAMX,YACA,qBAMG;CACH,MAAM,SAAS,mBAAmB;CAElC,MAAM,aACJ,OAAO,qBAAqB,YAAY,qBAAqB;CAC/D,MAAM,iBAAiB,aAClB,iBAAwC,SACxC;CAEL,MAAM,QAAQ,WACZ,aACI,cAAc,YAAY;EACxB,GAAI;EACJ;EACD,CAAM,GACP,cAAc,YAAY,OAAY;CAE5C,MAAM,UAAU,KAAK,kBAAkB,OAAO,OAAO;AAGrD,KAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAAS,KAAK,kBAAkB,UAAU,CAAC;IAC3C;AACF,SAAO;;AAIX,QAAO"}

package/dist/esm/client/useDictionaryDynamic.mjs

@@ -1,12 +1,16 @@
 import { getDictionary } from "../getDictionary.mjs";
 import { getIntlayerClient } from "./installIntlayer.mjs";
 import { internationalization } from "@intlayer/config/built";
+import { getDictionarySelectorCacheKey, isQualifiedDynamicLoaderMap, parseDictionarySelector, resolveQualifiedDynamicContentAsync } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/client/useDictionaryDynamic.ts
 /** Simple in-memory cache shared across all calls in the same page. */
 const cache = /* @__PURE__ */ new Map();
 /** Tracks in-flight loads to avoid duplicate fetches. */
 const inflight = /* @__PURE__ */ new Map();
+/** Resolved-content cache for qualified (collection/variant/meta) keys. */
+const qualifiedCache = /* @__PURE__ */ new Map();
+const qualifiedInflight = /* @__PURE__ */ new Map();
 const loadDictionary = (cacheKey, loader) => {
 	if (cache.has(cacheKey)) return Promise.resolve();
 	if (inflight.has(cacheKey)) return inflight.get(cacheKey);
@@ -17,39 +21,78 @@ const loadDictionary = (cacheKey, loader) => {
 	inflight.set(cacheKey, promise);
 	return promise;
 };
+/** Placeholder proxy — safe for any property access while loading. */
+const recursiveProxy = new Proxy(() => {}, {
+	get: (_t, prop) => {
+		if (prop === Symbol.toPrimitive) return () => "";
+		if (prop === "toString") return () => "";
+		if (prop === "valueOf") return () => "";
+		if (prop === "then") return void 0;
+		if (prop === "onChange") return (_cb) => recursiveProxy;
+		return recursiveProxy;
+	},
+	apply: () => recursiveProxy
+});
 /**
-* Dynamically load and transform a locale-keyed dictionary.
+* Dynamically load and transform a dictionary (plain or qualified).
 *
-* Works like `useIntlayer` / `useDictionary` but accepts a locale-keyed map
-* of lazy loaders instead of a pre-imported dictionary. Call it inside your
-* render function — the first call triggers a background fetch and returns
-* placeholder values; when the load completes the client notifies all
-* subscribers (including your render loop) so the render runs again with real
-* content. Subsequent calls for the same locale return immediately from cache.
+* For a qualified loader map (collection / variant / meta record, possibly
+* combined), only the chunk(s) the selector targets are loaded. For a plain
+* loader map, the locale chunk is loaded. The first call returns a placeholder
+* and triggers a background load; the client then notifies subscribers so the
+* render runs again with real content.
 *
-* Locale switches follow the same two-phase pattern: placeholder on first
-* render, real content after the locale bundle loads.
-*
-* @param dictionaryLoaders - Locale-keyed map of `() => Promise<Dictionary>`.
+* @param dictionaryLoaders - Locale-keyed loader map, or a qualified loader map.
 * @param key               - Dictionary key (used for cache namespacing).
-* @param locale            - Optional locale override.
-*
-* @example
-* ```ts
-* import dynDic from '../.intlayer/dynamic_dictionary/app.mjs';
-*
-* const render = () => {
-*   const content = useDictionaryDynamic(dynDic, 'app');
-*   document.querySelector('h1')!.textContent = String(content.title);
-* };
-*
-* render();
-* getIntlayerClient().subscribe(() => render());
-* ```
+* @param localeOrSelector  - Optional locale or selector.
 */
-const useDictionaryDynamic = (dictionaryLoaders, key, locale) => {
+const useDictionaryDynamic = (dictionaryLoaders, key, localeOrSelector) => {
 	const client = getIntlayerClient();
-	const currentLocale = locale ?? client.locale ?? internationalization.defaultLocale;
+	const defaultLocale = internationalization.defaultLocale;
+	if (isQualifiedDynamicLoaderMap(dictionaryLoaders)) {
+		const loaderMap = dictionaryLoaders;
+		const { locale: selectorLocale, selector } = parseDictionarySelector(localeOrSelector);
+		const selectorId = getDictionarySelectorCacheKey(selector);
+		const buildKey = (locale) => `${String(key)}.${locale}.${selectorId}`;
+		const resolveContent = (locale) => resolveQualifiedDynamicContentAsync({
+			loaderMap,
+			key: String(key),
+			locale,
+			selector,
+			transform: (dictionary) => getDictionary(dictionary, locale)
+		});
+		const currentLocale = selectorLocale ?? client.locale ?? defaultLocale;
+		const cacheKey = buildKey(currentLocale);
+		const attachOnChange = (content) => {
+			if (content != null && typeof content === "object") content.onChange = (callback) => {
+				client.subscribe((newLocale) => {
+					const locale = selectorLocale ?? newLocale;
+					const newKey = buildKey(locale);
+					if (qualifiedCache.has(newKey)) {
+						callback(qualifiedCache.get(newKey));
+						return;
+					}
+					resolveContent(locale).then((resolved) => {
+						qualifiedCache.set(newKey, resolved);
+						callback(resolved);
+					});
+				});
+				return content;
+			};
+			return content;
+		};
+		if (qualifiedCache.has(cacheKey)) return attachOnChange(qualifiedCache.get(cacheKey));
+		if (!qualifiedInflight.has(cacheKey)) {
+			const promise = resolveContent(currentLocale).then((resolved) => {
+				qualifiedCache.set(cacheKey, resolved);
+				qualifiedInflight.delete(cacheKey);
+				client.notify();
+			});
+			qualifiedInflight.set(cacheKey, promise);
+		}
+		return recursiveProxy;
+	}
+	const currentLocale = (typeof localeOrSelector === "string" ? localeOrSelector : void 0) ?? client.locale ?? defaultLocale;
 	const cacheKey = `${String(key)}.${currentLocale}`;
 	const loader = dictionaryLoaders[currentLocale];
 	const cached = cache.get(cacheKey);
@@ -72,17 +115,6 @@ const useDictionaryDynamic = (dictionaryLoaders, key, locale) => {
 	if (loader) loadDictionary(cacheKey, loader).then(() => {
 		client.notify();
 	});
-	const recursiveProxy = new Proxy(() => {}, {
-		get: (_t, prop) => {
-			if (prop === Symbol.toPrimitive) return () => "";
-			if (prop === "toString") return () => "";
-			if (prop === "valueOf") return () => "";
-			if (prop === "then") return void 0;
-			if (prop === "onChange") return (_cb) => recursiveProxy;
-			return recursiveProxy;
-		},
-		apply: () => recursiveProxy
-	});
 	return recursiveProxy;
 };
 

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

@@ -1 +1 @@
-{"version":3,"file":"useDictionaryDynamic.mjs","names":[],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport type { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DictionaryKeys,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/** Simple in-memory cache shared across all calls in the same page. */\nconst cache = new Map<string, Dictionary>();\n\n/** Tracks in-flight loads to avoid duplicate fetches. */\nconst inflight = new Map<string, Promise<void>>();\n\nconst loadDictionary = <T extends Dictionary>(\n  cacheKey: string,\n  loader: () => Promise<T>\n): Promise<void> => {\n  if (cache.has(cacheKey)) return Promise.resolve();\n  if (inflight.has(cacheKey)) return inflight.get(cacheKey)!;\n\n  const promise = loader().then((dictionary) => {\n    cache.set(cacheKey, dictionary);\n    inflight.delete(cacheKey);\n  });\n\n  inflight.set(cacheKey, promise);\n  return promise;\n};\n\n/**\n * Dynamically load and transform a locale-keyed dictionary.\n *\n * Works like `useIntlayer` / `useDictionary` but accepts a locale-keyed map\n * of lazy loaders instead of a pre-imported dictionary. Call it inside your\n * render function — the first call triggers a background fetch and returns\n * placeholder values; when the load completes the client notifies all\n * subscribers (including your render loop) so the render runs again with real\n * content. Subsequent calls for the same locale return immediately from cache.\n *\n * Locale switches follow the same two-phase pattern: placeholder on first\n * render, real content after the locale bundle loads.\n *\n * @param dictionaryLoaders - Locale-keyed map of `() => Promise<Dictionary>`.\n * @param key               - Dictionary key (used for cache namespacing).\n * @param locale            - Optional locale override.\n *\n * @example\n * ```ts\n * import dynDic from '../.intlayer/dynamic_dictionary/app.mjs';\n *\n * const render = () => {\n *   const content = useDictionaryDynamic(dynDic, 'app');\n *   document.querySelector('h1')!.textContent = String(content.title);\n * };\n *\n * render();\n * getIntlayerClient().subscribe(() => render());\n * ```\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const L extends LocalesValues = LocalesValues,\n>(\n  dictionaryLoaders: StrictModeLocaleMap<() => Promise<T>>,\n  key: K,\n  locale?: L\n): WithOnChange<DeepTransformContent<T['content'], L>> => {\n  const client = getIntlayerClient();\n  const currentLocale = (locale ??\n    client.locale ??\n    internationalization.defaultLocale) as L;\n\n  const cacheKey = `${String(key)}.${currentLocale}`;\n  const loader = (dictionaryLoaders as Record<string, () => Promise<T>>)[\n    currentLocale\n  ];\n\n  // --- Cache hit: return real content synchronously ---\n  const cached = cache.get(cacheKey);\n  if (cached) {\n    const content = getDictionary(cached as T, currentLocale) as WithOnChange<\n      DeepTransformContent<T['content'], L>\n    >;\n\n    content.onChange = (\n      callback: (content: DeepTransformContent<T['content'], L>) => void\n    ) => {\n      // Re-fire whenever content reloads (locale change → new cache entry).\n      client.subscribe((newLocale) => {\n        const newKey = `${String(key)}.${newLocale}`;\n        const newLoader = (\n          dictionaryLoaders as Record<string, () => Promise<T>>\n        )[newLocale];\n\n        if (!newLoader) return;\n\n        loadDictionary(newKey, newLoader).then(() => {\n          const dict = cache.get(newKey);\n          if (dict) {\n            callback(\n              getDictionary(dict as T, newLocale as L) as DeepTransformContent<\n                T['content'],\n                L\n              >\n            );\n          }\n        });\n      });\n\n      return content;\n    };\n\n    return content;\n  }\n\n  // --- Cache miss: kick off background load, then notify to re-render ---\n  if (loader) {\n    loadDictionary(cacheKey, loader).then(() => {\n      client.notify();\n    });\n  }\n\n  // Placeholder proxy — safe for any property access while loading.\n  const recursiveProxy: any = new Proxy(() => {}, {\n    get: (_t, prop) => {\n      if (prop === Symbol.toPrimitive) return () => '';\n      if (prop === 'toString') return () => '';\n      if (prop === 'valueOf') return () => '';\n      if (prop === 'then') return undefined; // not a Promise\n      if (prop === 'onChange') return (_cb: any) => recursiveProxy;\n      return recursiveProxy;\n    },\n    apply: () => recursiveProxy,\n  });\n\n  return recursiveProxy as WithOnChange<DeepTransformContent<T['content'], L>>;\n};\n"],"mappings":";;;;;;AAaA,MAAM,wBAAQ,IAAI,KAAyB;;AAG3C,MAAM,2BAAW,IAAI,KAA4B;AAEjD,MAAM,kBACJ,UACA,WACkB;AAClB,KAAI,MAAM,IAAI,SAAS,CAAE,QAAO,QAAQ,SAAS;AACjD,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO,SAAS,IAAI,SAAS;CAEzD,MAAM,UAAU,QAAQ,CAAC,MAAM,eAAe;AAC5C,QAAM,IAAI,UAAU,WAAW;AAC/B,WAAS,OAAO,SAAS;GACzB;AAEF,UAAS,IAAI,UAAU,QAAQ;AAC/B,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCT,MAAa,wBAKX,mBACA,KACA,WACwD;CACxD,MAAM,SAAS,mBAAmB;CAClC,MAAM,gBAAiB,UACrB,OAAO,UACP,qBAAqB;CAEvB,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,GAAG;CACnC,MAAM,SAAU,kBACd;CAIF,MAAM,SAAS,MAAM,IAAI,SAAS;AAClC,KAAI,QAAQ;EACV,MAAM,UAAU,cAAc,QAAa,cAAc;AAIzD,UAAQ,YACN,aACG;AAEH,UAAO,WAAW,cAAc;IAC9B,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,GAAG;IACjC,MAAM,YACJ,kBACA;AAEF,QAAI,CAAC,UAAW;AAEhB,mBAAe,QAAQ,UAAU,CAAC,WAAW;KAC3C,MAAM,OAAO,MAAM,IAAI,OAAO;AAC9B,SAAI,KACF,UACE,cAAc,MAAW,UAAe,CAIzC;MAEH;KACF;AAEF,UAAO;;AAGT,SAAO;;AAIT,KAAI,OACF,gBAAe,UAAU,OAAO,CAAC,WAAW;AAC1C,SAAO,QAAQ;GACf;CAIJ,MAAM,iBAAsB,IAAI,YAAY,IAAI;EAC9C,MAAM,IAAI,SAAS;AACjB,OAAI,SAAS,OAAO,YAAa,cAAa;AAC9C,OAAI,SAAS,WAAY,cAAa;AACtC,OAAI,SAAS,UAAW,cAAa;AACrC,OAAI,SAAS,OAAQ,QAAO;AAC5B,OAAI,SAAS,WAAY,SAAQ,QAAa;AAC9C,UAAO;;EAET,aAAa;EACd,CAAC;AAEF,QAAO"}
+{"version":3,"file":"useDictionaryDynamic.mjs","names":[],"sources":["../../../src/client/useDictionaryDynamic.ts"],"sourcesContent":["import { internationalization } from '@intlayer/config/built';\nimport {\n  getDictionarySelectorCacheKey,\n  isQualifiedDynamicLoaderMap,\n  parseDictionarySelector,\n  type QualifiedDynamicLoaderMap,\n  resolveQualifiedDynamicContentAsync,\n} from '@intlayer/core/dictionaryManipulator';\nimport type {\n  Dictionary,\n  DictionarySelector,\n} from '@intlayer/types/dictionary';\nimport type {\n  DictionaryKeys,\n  DictionarySelectorForKey,\n  LocalesValues,\n  StrictModeLocaleMap,\n} from '@intlayer/types/module_augmentation';\nimport { getDictionary } from '../getDictionary';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/** Simple in-memory cache shared across all calls in the same page. */\nconst cache = new Map<string, Dictionary>();\n\n/** Tracks in-flight loads to avoid duplicate fetches. */\nconst inflight = new Map<string, Promise<void>>();\n\n/** Resolved-content cache for qualified (collection/variant/meta) keys. */\nconst qualifiedCache = new Map<string, unknown>();\nconst qualifiedInflight = new Map<string, Promise<void>>();\n\nconst loadDictionary = <T extends Dictionary>(\n  cacheKey: string,\n  loader: () => Promise<T>\n): Promise<void> => {\n  if (cache.has(cacheKey)) return Promise.resolve();\n  if (inflight.has(cacheKey)) return inflight.get(cacheKey)!;\n\n  const promise = loader().then((dictionary) => {\n    cache.set(cacheKey, dictionary);\n    inflight.delete(cacheKey);\n  });\n\n  inflight.set(cacheKey, promise);\n  return promise;\n};\n\n/** Placeholder proxy — safe for any property access while loading. */\nconst recursiveProxy: any = new Proxy(() => {}, {\n  get: (_t, prop) => {\n    if (prop === Symbol.toPrimitive) return () => '';\n    if (prop === 'toString') return () => '';\n    if (prop === 'valueOf') return () => '';\n    if (prop === 'then') return undefined; // not a Promise\n    if (prop === 'onChange') return (_cb: any) => recursiveProxy;\n    return recursiveProxy;\n  },\n  apply: () => recursiveProxy,\n});\n\n/**\n * Dynamically load and transform a dictionary (plain or qualified).\n *\n * For a qualified loader map (collection / variant / meta record, possibly\n * combined), only the chunk(s) the selector targets are loaded. For a plain\n * loader map, the locale chunk is loaded. The first call returns a placeholder\n * and triggers a background load; the client then notifies subscribers so the\n * render runs again with real content.\n *\n * @param dictionaryLoaders - Locale-keyed loader map, or a qualified loader map.\n * @param key               - Dictionary key (used for cache namespacing).\n * @param localeOrSelector  - Optional locale or selector.\n */\nexport const useDictionaryDynamic = <\n  const T extends Dictionary,\n  const K extends DictionaryKeys,\n  const A extends LocalesValues | DictionarySelectorForKey<K> = LocalesValues,\n>(\n  dictionaryLoaders:\n    | StrictModeLocaleMap<() => Promise<T>>\n    | QualifiedDynamicLoaderMap,\n  key: K,\n  localeOrSelector?: A\n): WithOnChange<DeepTransformContent<T['content']>> => {\n  const client = getIntlayerClient();\n  const defaultLocale = internationalization.defaultLocale;\n\n  // --- Qualified loader map (collection / variant / meta record) ---\n  if (isQualifiedDynamicLoaderMap(dictionaryLoaders)) {\n    const loaderMap = dictionaryLoaders;\n    const { locale: selectorLocale, selector } =\n      parseDictionarySelector<LocalesValues>(localeOrSelector);\n    const selectorId = getDictionarySelectorCacheKey(selector);\n\n    const buildKey = (locale: string) =>\n      `${String(key)}.${locale}.${selectorId}`;\n    const resolveContent = (locale: LocalesValues) =>\n      resolveQualifiedDynamicContentAsync({\n        loaderMap,\n        key: String(key),\n        locale,\n        selector,\n        transform: (dictionary) => getDictionary(dictionary, locale),\n      });\n\n    const currentLocale = (selectorLocale ??\n      client.locale ??\n      defaultLocale) as LocalesValues;\n    const cacheKey = buildKey(currentLocale);\n\n    const attachOnChange = (content: any) => {\n      if (content != null && typeof content === 'object') {\n        content.onChange = (callback: (c: any) => void) => {\n          client.subscribe((newLocale) => {\n            const locale = (selectorLocale ?? newLocale) as LocalesValues;\n            const newKey = buildKey(locale);\n\n            if (qualifiedCache.has(newKey)) {\n              callback(qualifiedCache.get(newKey));\n              return;\n            }\n\n            resolveContent(locale).then((resolved) => {\n              qualifiedCache.set(newKey, resolved);\n              callback(resolved);\n            });\n          });\n          return content;\n        };\n      }\n      return content;\n    };\n\n    if (qualifiedCache.has(cacheKey)) {\n      return attachOnChange(qualifiedCache.get(cacheKey)) as any;\n    }\n\n    if (!qualifiedInflight.has(cacheKey)) {\n      const promise = resolveContent(currentLocale).then((resolved) => {\n        qualifiedCache.set(cacheKey, resolved);\n        qualifiedInflight.delete(cacheKey);\n        client.notify();\n      });\n      qualifiedInflight.set(cacheKey, promise);\n    }\n\n    return recursiveProxy;\n  }\n\n  // --- Plain locale-keyed loader map ---\n  const locale =\n    typeof localeOrSelector === 'string'\n      ? (localeOrSelector as LocalesValues)\n      : undefined;\n  const currentLocale = (locale ?? client.locale ?? defaultLocale) as A;\n\n  const cacheKey = `${String(key)}.${currentLocale}`;\n  const loader = (dictionaryLoaders as Record<string, () => Promise<T>>)[\n    currentLocale as string\n  ];\n\n  // --- Cache hit: return real content synchronously ---\n  const cached = cache.get(cacheKey);\n  if (cached) {\n    const content = getDictionary(cached, currentLocale) as WithOnChange<\n      DeepTransformContent<T['content']>\n    >;\n\n    content.onChange = (callback) => {\n      // Re-fire whenever content reloads (locale change → new cache entry).\n      client.subscribe((newLocale) => {\n        const newKey = `${String(key)}.${newLocale}`;\n        const newLoader = (\n          dictionaryLoaders as Record<string, () => Promise<T>>\n        )[newLocale];\n\n        if (!newLoader) return;\n\n        loadDictionary(newKey, newLoader).then(() => {\n          const dict = cache.get(newKey);\n          if (dict) {\n            callback(getDictionary(dict, newLocale as A) as any);\n          }\n        });\n      });\n\n      return content;\n    };\n\n    return content;\n  }\n\n  // --- Cache miss: kick off background load, then notify to re-render ---\n  if (loader) {\n    loadDictionary(cacheKey, loader).then(() => {\n      client.notify();\n    });\n  }\n\n  return recursiveProxy;\n};\n"],"mappings":";;;;;;;AAwBA,MAAM,wBAAQ,IAAI,KAAyB;;AAG3C,MAAM,2BAAW,IAAI,KAA4B;;AAGjD,MAAM,iCAAiB,IAAI,KAAsB;AACjD,MAAM,oCAAoB,IAAI,KAA4B;AAE1D,MAAM,kBACJ,UACA,WACkB;AAClB,KAAI,MAAM,IAAI,SAAS,CAAE,QAAO,QAAQ,SAAS;AACjD,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO,SAAS,IAAI,SAAS;CAEzD,MAAM,UAAU,QAAQ,CAAC,MAAM,eAAe;AAC5C,QAAM,IAAI,UAAU,WAAW;AAC/B,WAAS,OAAO,SAAS;GACzB;AAEF,UAAS,IAAI,UAAU,QAAQ;AAC/B,QAAO;;;AAIT,MAAM,iBAAsB,IAAI,YAAY,IAAI;CAC9C,MAAM,IAAI,SAAS;AACjB,MAAI,SAAS,OAAO,YAAa,cAAa;AAC9C,MAAI,SAAS,WAAY,cAAa;AACtC,MAAI,SAAS,UAAW,cAAa;AACrC,MAAI,SAAS,OAAQ,QAAO;AAC5B,MAAI,SAAS,WAAY,SAAQ,QAAa;AAC9C,SAAO;;CAET,aAAa;CACd,CAAC;;;;;;;;;;;;;;AAeF,MAAa,wBAKX,mBAGA,KACA,qBACqD;CACrD,MAAM,SAAS,mBAAmB;CAClC,MAAM,gBAAgB,qBAAqB;AAG3C,KAAI,4BAA4B,kBAAkB,EAAE;EAClD,MAAM,YAAY;EAClB,MAAM,EAAE,QAAQ,gBAAgB,aAC9B,wBAAuC,iBAAiB;EAC1D,MAAM,aAAa,8BAA8B,SAAS;EAE1D,MAAM,YAAY,WAChB,GAAG,OAAO,IAAI,CAAC,GAAG,OAAO,GAAG;EAC9B,MAAM,kBAAkB,WACtB,oCAAoC;GAClC;GACA,KAAK,OAAO,IAAI;GAChB;GACA;GACA,YAAY,eAAe,cAAc,YAAY,OAAO;GAC7D,CAAC;EAEJ,MAAM,gBAAiB,kBACrB,OAAO,UACP;EACF,MAAM,WAAW,SAAS,cAAc;EAExC,MAAM,kBAAkB,YAAiB;AACvC,OAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAA+B;AACjD,WAAO,WAAW,cAAc;KAC9B,MAAM,SAAU,kBAAkB;KAClC,MAAM,SAAS,SAAS,OAAO;AAE/B,SAAI,eAAe,IAAI,OAAO,EAAE;AAC9B,eAAS,eAAe,IAAI,OAAO,CAAC;AACpC;;AAGF,oBAAe,OAAO,CAAC,MAAM,aAAa;AACxC,qBAAe,IAAI,QAAQ,SAAS;AACpC,eAAS,SAAS;OAClB;MACF;AACF,WAAO;;AAGX,UAAO;;AAGT,MAAI,eAAe,IAAI,SAAS,CAC9B,QAAO,eAAe,eAAe,IAAI,SAAS,CAAC;AAGrD,MAAI,CAAC,kBAAkB,IAAI,SAAS,EAAE;GACpC,MAAM,UAAU,eAAe,cAAc,CAAC,MAAM,aAAa;AAC/D,mBAAe,IAAI,UAAU,SAAS;AACtC,sBAAkB,OAAO,SAAS;AAClC,WAAO,QAAQ;KACf;AACF,qBAAkB,IAAI,UAAU,QAAQ;;AAG1C,SAAO;;CAQT,MAAM,iBAHJ,OAAO,qBAAqB,WACvB,mBACD,WAC2B,OAAO,UAAU;CAElD,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,GAAG;CACnC,MAAM,SAAU,kBACd;CAIF,MAAM,SAAS,MAAM,IAAI,SAAS;AAClC,KAAI,QAAQ;EACV,MAAM,UAAU,cAAc,QAAQ,cAAc;AAIpD,UAAQ,YAAY,aAAa;AAE/B,UAAO,WAAW,cAAc;IAC9B,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,GAAG;IACjC,MAAM,YACJ,kBACA;AAEF,QAAI,CAAC,UAAW;AAEhB,mBAAe,QAAQ,UAAU,CAAC,WAAW;KAC3C,MAAM,OAAO,MAAM,IAAI,OAAO;AAC9B,SAAI,KACF,UAAS,cAAc,MAAM,UAAe,CAAQ;MAEtD;KACF;AAEF,UAAO;;AAGT,SAAO;;AAIT,KAAI,OACF,gBAAe,UAAU,OAAO,CAAC,WAAW;AAC1C,SAAO,QAAQ;GACf;AAGJ,QAAO"}

package/dist/esm/client/useIntlayer.mjs

@@ -7,28 +7,17 @@ import { getIntlayerClient } from "./installIntlayer.mjs";
 * locale changes via the chainable `.onChange()` method — mirroring the API
 * of `react-intlayer`'s `useIntlayer`.
 *
-* Unlike React (where the hook system automatically re-runs on re-render),
-* vanilla JS has no component lifecycle. The `.onChange()` callback is the
-* explicit equivalent: it is called with fresh content whenever the active
-* locale changes. Use it to patch your DOM or trigger a full re-render.
+* 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)
+* - `{ id: 'prod_abc', ...metaFields }` — meta record
+* - `locale` composes with any selector and overrides the current locale
 *
 * The function returns the current content **directly** (same shape as
-* `getIntlayer(key)`), plus the `.onChange()` helper:
+* `getIntlayer(key)`), plus the `.onChange()` helper.
 *
-* ```ts
-* // React
-* const content = useIntlayer('app');
-*
-* // Vanilla — identical surface API, opt-in reactivity via .onChange()
-* const content = useIntlayer('app');
-* const content = useIntlayer('app').onChange((c) => render(c));
-* ```
-*
-* For cleanup (e.g. Vite HMR), subscribe via `getIntlayerClient().subscribe()`
-* and hold the returned unsubscribe function.
-*
-* @param key    - Dictionary key registered in your intlayer content files.
-* @param locale - Optional locale override (defaults to the current app locale).
+* @param key - Dictionary key registered in your intlayer content files.
+* @param localeOrSelector - Optional locale or selector.
 * @returns The current translated content with an `.onChange()` method.
 *
 * @example
@@ -37,22 +26,22 @@ import { getIntlayerClient } from "./installIntlayer.mjs";
 *
 * installIntlayer();
 *
-* // Static read (no subscription)
 * const content = useIntlayer('homepage');
-* document.querySelector('h1').textContent = String(content.title);
-*
-* // Reactive read — onChange is called on every locale change
-* useIntlayer('homepage').onChange((c) => {
-*   document.querySelector('h1').textContent = String(c.title);
-* });
+* const faq2 = useIntlayer('faq', { item: 2 });
 * ```
 */
-const useIntlayer = (key, locale) => {
+const useIntlayer = (key, localeOrSelector) => {
 	const client = getIntlayerClient();
-	const content = getIntlayer(key, locale ?? client.locale);
-	content.onChange = (callback) => {
+	const isSelector = typeof localeOrSelector === "object" && localeOrSelector !== null;
+	const explicitLocale = isSelector ? localeOrSelector.locale : localeOrSelector;
+	const read = (locale) => isSelector ? getIntlayer(key, {
+		...localeOrSelector,
+		locale
+	}) : getIntlayer(key, locale);
+	const content = read(explicitLocale ?? client.locale);
+	if (content != null && typeof content === "object") content.onChange = (callback) => {
 		client.subscribe((newLocale) => {
-			callback(getIntlayer(key, locale ?? newLocale));
+			callback(read(explicitLocale ?? newLocale));
 		});
 		return content;
 	};

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

@@ -1 +1 @@
-{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["import type {\n  DictionaryKeys,\n  DictionaryRegistryContent,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/**\n * Get the translated content for the given key and optionally subscribe to\n * locale changes via the chainable `.onChange()` method — mirroring the API\n * of `react-intlayer`'s `useIntlayer`.\n *\n * Unlike React (where the hook system automatically re-runs on re-render),\n * vanilla JS has no component lifecycle. The `.onChange()` callback is the\n * explicit equivalent: it is called with fresh content whenever the active\n * locale changes. Use it to patch your DOM or trigger a full re-render.\n *\n * The function returns the current content **directly** (same shape as\n * `getIntlayer(key)`), plus the `.onChange()` helper:\n *\n * ```ts\n * // React\n * const content = useIntlayer('app');\n *\n * // Vanilla — identical surface API, opt-in reactivity via .onChange()\n * const content = useIntlayer('app');\n * const content = useIntlayer('app').onChange((c) => render(c));\n * ```\n *\n * For cleanup (e.g. Vite HMR), subscribe via `getIntlayerClient().subscribe()`\n * and hold the returned unsubscribe function.\n *\n * @param key    - Dictionary key registered in your intlayer content files.\n * @param locale - Optional locale override (defaults to the current app locale).\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import { installIntlayer, useIntlayer } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * // Static read (no subscription)\n * const content = useIntlayer('homepage');\n * document.querySelector('h1').textContent = String(content.title);\n *\n * // Reactive read — onChange is called on every locale change\n * useIntlayer('homepage').onChange((c) => {\n *   document.querySelector('h1').textContent = String(c.title);\n * });\n * ```\n */\nexport const useIntlayer = <const T extends DictionaryKeys>(\n  key: T,\n  locale?: LocalesValues\n): WithOnChange<DeepTransformContent<DictionaryRegistryContent<T>>> => {\n  const client = getIntlayerClient();\n  const content = getIntlayer(key, locale ?? client.locale) as WithOnChange<\n    DeepTransformContent<DictionaryRegistryContent<T>>\n  >;\n\n  content.onChange = (callback) => {\n    client.subscribe((newLocale) => {\n      callback(getIntlayer(key, (locale ?? newLocale) as typeof locale));\n    });\n    return content;\n  };\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,MAAa,eACX,KACA,WACqE;CACrE,MAAM,SAAS,mBAAmB;CAClC,MAAM,UAAU,YAAY,KAAK,UAAU,OAAO,OAAO;AAIzD,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAAS,YAAY,KAAM,UAAU,UAA4B,CAAC;IAClE;AACF,SAAO;;AAGT,QAAO"}
+{"version":3,"file":"useIntlayer.mjs","names":[],"sources":["../../../src/client/useIntlayer.ts"],"sourcesContent":["import type { DictionarySelector } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  DictionaryKeys,\n  DictionaryRegistryResult,\n  DictionarySelectorForKey,\n  ExtractSelectorLocale,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { getIntlayer } from '../getIntlayer';\nimport type { DeepTransformContent } from '../plugins';\nimport { getIntlayerClient } from './installIntlayer';\nimport type { WithOnChange } from './useDictionary';\n\n/**\n * Get the translated content for the given key and optionally subscribe to\n * locale changes via the chainable `.onChange()` method — mirroring the API\n * of `react-intlayer`'s `useIntlayer`.\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 * - `{ id: 'prod_abc', ...metaFields }` — meta record\n * - `locale` composes with any selector and overrides the current locale\n *\n * The function returns the current content **directly** (same shape as\n * `getIntlayer(key)`), plus the `.onChange()` helper.\n *\n * @param key - Dictionary key registered in your intlayer content files.\n * @param localeOrSelector - Optional locale or selector.\n * @returns The current translated content with an `.onChange()` method.\n *\n * @example\n * ```ts\n * import { installIntlayer, useIntlayer } from 'vanilla-intlayer';\n *\n * installIntlayer();\n *\n * const content = useIntlayer('homepage');\n * const faq2 = useIntlayer('faq', { item: 2 });\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): WithOnChange<\n  DeepTransformContent<DictionaryRegistryResult<T, A>, ExtractSelectorLocale<A>>\n> => {\n  const client = getIntlayerClient();\n\n  const isSelector =\n    typeof localeOrSelector === 'object' && localeOrSelector !== null;\n  const explicitLocale = isSelector\n    ? (localeOrSelector as DictionarySelector).locale\n    : (localeOrSelector as LocalesValues | undefined);\n\n  const read = (locale: LocalesValues | undefined) =>\n    isSelector\n      ? getIntlayer(key, {\n          ...(localeOrSelector as DictionarySelector),\n          locale,\n        } as A)\n      : getIntlayer(key, locale as A);\n\n  const content = read(explicitLocale ?? client.locale) as WithOnChange<any>;\n\n  // A selector can resolve to null/array; only objects carry `.onChange`.\n  if (content != null && typeof content === 'object') {\n    content.onChange = (callback) => {\n      client.subscribe((newLocale) => {\n        callback(read(explicitLocale ?? newLocale));\n      });\n      return content;\n    };\n  }\n\n  return content;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAa,eAIX,KACA,qBAGG;CACH,MAAM,SAAS,mBAAmB;CAElC,MAAM,aACJ,OAAO,qBAAqB,YAAY,qBAAqB;CAC/D,MAAM,iBAAiB,aAClB,iBAAwC,SACxC;CAEL,MAAM,QAAQ,WACZ,aACI,YAAY,KAAK;EACf,GAAI;EACJ;EACD,CAAM,GACP,YAAY,KAAK,OAAY;CAEnC,MAAM,UAAU,KAAK,kBAAkB,OAAO,OAAO;AAGrD,KAAI,WAAW,QAAQ,OAAO,YAAY,SACxC,SAAQ,YAAY,aAAa;AAC/B,SAAO,WAAW,cAAc;AAC9B,YAAS,KAAK,kBAAkB,UAAU,CAAC;IAC3C;AACF,SAAO;;AAIX,QAAO"}

package/dist/esm/getDictionary.mjs

@@ -2,7 +2,14 @@ import { getPlugins } from "./plugins.mjs";
 import { getDictionary as getDictionary$1 } from "@intlayer/core/interpreter";
 
 //#region src/getDictionary.ts
-const getDictionary = (dictionary, locale) => getDictionary$1(dictionary, locale, getPlugins(locale));
+/**
+* Transforms a dictionary (or qualified dictionary group) and returns its
+* content for the given locale or selector (`{ item }`, `{ variant }`,
+* `{ id, ...meta }`, optionally combined with `locale`).
+*/
+const getDictionary = (dictionary, localeOrSelector) => {
+	return getDictionary$1(dictionary, localeOrSelector, getPlugins(typeof localeOrSelector === "object" && localeOrSelector !== null ? localeOrSelector.locale : localeOrSelector));
+};
 
 //#endregion
 export { getDictionary };

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 { Dictionary } from '@intlayer/types/dictionary';\nimport type {\n  DeclaredLocales,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\nexport const getDictionary = <\n  const T extends Dictionary,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  dictionary: T,\n  locale?: L\n): DeepTransformContent<T['content'], L> =>\n  getDictionaryCore(dictionary, locale, getPlugins(locale)) as any;\n"],"mappings":";;;;AAQA,MAAa,iBAIX,YACA,WAEAA,gBAAkB,YAAY,QAAQ,WAAW,OAAO,CAAC"}
+{"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  DictionarySelector,\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 * `{ id, ...meta }`, 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":";;;;;;;;;AAoBA,MAAa,iBAMX,YACA,qBAIG;AAOH,QAAOA,gBACL,YACA,kBACA,WARA,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,iBAMc,CACnB"}

package/dist/esm/getIntlayer.mjs

@@ -2,7 +2,14 @@ import { getPlugins } from "./plugins.mjs";
 import { getIntlayer as getIntlayer$1 } from "@intlayer/core/interpreter";
 
 //#region src/getIntlayer.ts
-const getIntlayer = (key, locale) => getIntlayer$1(key, locale, getPlugins(locale));
+/**
+* Picks one dictionary by its key and returns its content for the given
+* locale or selector (`{ item }`, `{ variant }`, `{ id, ...meta }`,
+* optionally combined with `locale`).
+*/
+const getIntlayer = (key, localeOrSelector) => {
+	return getIntlayer$1(key, localeOrSelector, getPlugins(typeof localeOrSelector === "object" && localeOrSelector !== null ? localeOrSelector.locale : localeOrSelector));
+};
 
 //#endregion
 export { getIntlayer };

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  DictionaryRegistryContent,\n  LocalesValues,\n} from '@intlayer/types/module_augmentation';\nimport { type DeepTransformContent, getPlugins } from './plugins';\n\nexport const getIntlayer = <\n  const T extends DictionaryKeys,\n  const L extends LocalesValues = DeclaredLocales,\n>(\n  key: T,\n  locale?: L\n): DeepTransformContent<DictionaryRegistryContent<T>, L> =>\n  getIntlayerCore(key, locale, getPlugins(locale)) as any;\n"],"mappings":";;;;AASA,MAAa,eAIX,KACA,WAEAA,cAAgB,KAAK,QAAQ,WAAW,OAAO,CAAC"}
+{"version":3,"file":"getIntlayer.mjs","names":["getIntlayerCore"],"sources":["../../src/getIntlayer.ts"],"sourcesContent":["import { getIntlayer as getIntlayerCore } from '@intlayer/core/interpreter';\nimport type { DictionarySelector } from '@intlayer/types/dictionary';\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 }`, `{ id, ...meta }`,\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":";;;;;;;;;AAiBA,MAAa,eAIX,KACA,qBAIG;AAOH,QAAOA,cAAgB,KAAK,kBAAkB,WAL5C,OAAO,qBAAqB,YAAY,qBAAqB,OACzD,iBAAiB,SACjB,iBAG0D,CAAC"}

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

@@ -1,6 +1,6 @@
 import { DeepTransformContent } from "../plugins.js";
-import { DeclaredLocales, LocalesValues } from "@intlayer/types/module_augmentation";
-import { Dictionary } from "@intlayer/types/dictionary";
+import { DeclaredLocales, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
+import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup, ResolveQualifiedDictionaryContent } from "@intlayer/types/dictionary";
 
 //#region src/client/useDictionary.d.ts
 type WithOnChange<T> = T & {
@@ -15,48 +15,21 @@ type WithOnChange<T> = T & {
    * });
    * ```
    */
-  onChange: (callback: <T extends Dictionary, L extends LocalesValues>(content: DeepTransformContent<T['content'], L>) => void) => WithOnChange<T>;
+  onChange: (callback: (content: any) => void) => WithOnChange<T>;
 };
 /**
- * Get the translated content for a raw dictionary object and optionally
- * subscribe to locale changes via the chainable `.onChange()` method —
- * mirroring the API of `react-intlayer`.
+ * Get the content for a raw dictionary (or qualified dictionary group) and
+ * optionally subscribe to locale changes via the chainable `.onChange()`
+ * method — mirroring the API of `react-intlayer`.
  *
- * Unlike `useIntlayer` (which takes a registered key), this function accepts a
- * dictionary object directly — useful for dictionaries loaded asynchronously
- * or defined inline.
+ * The second argument is either a locale or a selector object (`{ item }`,
+ * `{ variant }`, `{ id, ...meta }`, optionally combined with `locale`).
  *
- * The function returns the current content **directly** (same shape as
- * `getDictionary(dict)`), plus the `.onChange()` helper:
- *
- * ```ts
- * // React
- * const content = useDictionary(myDict);
- *
- * // Vanilla — identical surface API, opt-in reactivity via .onChange()
- * const content = useDictionary(myDict);
- * const content = useDictionary(myDict).onChange((c) => render(c));
- * ```
- *
- * @param dictionary - The raw dictionary object.
- * @param locale     - Optional locale override.
- * @returns The current translated content with an `.onChange()` method.
- *
- * @example
- * ```ts
- * import myDict from './myDictionary.content';
- * import { installIntlayer, useDictionary } from 'vanilla-intlayer';
- *
- * installIntlayer();
- *
- * const content = useDictionary(myDict).onChange((c) => {
- *   document.querySelector('p').textContent = String(c.greeting);
- * });
- *
- * document.querySelector('p').textContent = String(content.greeting);
- * ```
+ * @param dictionary - The raw dictionary (or qualified group) object.
+ * @param localeOrSelector - Optional locale or selector.
+ * @returns The current content with an `.onChange()` method.
  */
-declare const useDictionary: <const T extends Dictionary, const L extends LocalesValues = DeclaredLocales>(dictionary: T, locale?: L) => WithOnChange<DeepTransformContent<T["content"], L>>;
+declare const useDictionary: <const T extends Dictionary | QualifiedDictionaryGroup, const A extends LocalesValues | DictionarySelectorForGroup<T> = DeclaredLocales>(dictionary: T, localeOrSelector?: A) => WithOnChange<DeepTransformContent<ResolveQualifiedDictionaryContent<T, A>, ExtractSelectorLocale<A>>>;
 //#endregion
 export { WithOnChange, 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":";;;;;KASY,YAAA,MAAkB,CAAA;;AAA9B;;;;;;;;;;EAYE,QAAA,GACE,QAAA,aAAqB,UAAA,YAAsB,aAAA,EACzC,OAAA,EAAS,oBAAA,CAAqB,CAAA,aAAc,CAAA,eAE3C,YAAA,CAAa,CAAA;AAAA;;;;;;;;;;;;;;;;;;AA0CpB;;;;;;;;;;;;;;;;;;;;;;cAAa,aAAA,mBACK,UAAA,kBACA,aAAA,GAAgB,eAAA,EAEhC,UAAA,EAAY,CAAA,EACZ,MAAA,GAAS,CAAA,KACR,YAAA,CAAa,oBAAA,CAAqB,CAAA,aAAc,CAAA"}
+{"version":3,"file":"useDictionary.d.ts","names":[],"sources":["../../../src/client/useDictionary.ts"],"mappings":";;;;;KAgBY,YAAA,MAAkB,CAAA;;AAA9B;;;;;;;;;;EAYE,QAAA,GAAW,QAAA,GAAW,OAAA,mBAA0B,YAAA,CAAa,CAAA;AAAA;;;;;;AAe/D;;;;;;;cAAa,aAAA,mBACK,UAAA,GAAa,wBAAA,kBAEzB,aAAA,GACA,0BAAA,CAA2B,CAAA,IAAK,eAAA,EAEpC,UAAA,EAAY,CAAA,EACZ,gBAAA,GAAmB,CAAA,KAClB,YAAA,CACD,oBAAA,CACE,iCAAA,CAAkC,CAAA,EAAG,CAAA,GACrC,qBAAA,CAAsB,CAAA"}

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

@@ -1,40 +1,24 @@
 import { DeepTransformContent } from "../plugins.js";
 import { WithOnChange } from "./useDictionary.js";
-import { DictionaryKeys, LocalesValues, StrictModeLocaleMap } from "@intlayer/types/module_augmentation";
+import { DictionaryKeys, DictionarySelectorForKey, LocalesValues, StrictModeLocaleMap } from "@intlayer/types/module_augmentation";
 import { Dictionary } from "@intlayer/types/dictionary";
+import { QualifiedDynamicLoaderMap } from "@intlayer/core/dictionaryManipulator";
 
 //#region src/client/useDictionaryDynamic.d.ts
 /**
- * Dynamically load and transform a locale-keyed dictionary.
+ * Dynamically load and transform a dictionary (plain or qualified).
  *
- * Works like `useIntlayer` / `useDictionary` but accepts a locale-keyed map
- * of lazy loaders instead of a pre-imported dictionary. Call it inside your
- * render function — the first call triggers a background fetch and returns
- * placeholder values; when the load completes the client notifies all
- * subscribers (including your render loop) so the render runs again with real
- * content. Subsequent calls for the same locale return immediately from cache.
+ * For a qualified loader map (collection / variant / meta record, possibly
+ * combined), only the chunk(s) the selector targets are loaded. For a plain
+ * loader map, the locale chunk is loaded. The first call returns a placeholder
+ * and triggers a background load; the client then notifies subscribers so the
+ * render runs again with real content.
  *
- * Locale switches follow the same two-phase pattern: placeholder on first
- * render, real content after the locale bundle loads.
- *
- * @param dictionaryLoaders - Locale-keyed map of `() => Promise<Dictionary>`.
+ * @param dictionaryLoaders - Locale-keyed loader map, or a qualified loader map.
  * @param key               - Dictionary key (used for cache namespacing).
- * @param locale            - Optional locale override.
- *
- * @example
- * ```ts
- * import dynDic from '../.intlayer/dynamic_dictionary/app.mjs';
- *
- * const render = () => {
- *   const content = useDictionaryDynamic(dynDic, 'app');
- *   document.querySelector('h1')!.textContent = String(content.title);
- * };
- *
- * render();
- * getIntlayerClient().subscribe(() => render());
- * ```
+ * @param localeOrSelector  - Optional locale or selector.
  */
-declare const useDictionaryDynamic: <const T extends Dictionary, const K extends DictionaryKeys, const L extends LocalesValues = LocalesValues>(dictionaryLoaders: StrictModeLocaleMap<() => Promise<T>>, key: K, locale?: L) => WithOnChange<DeepTransformContent<T["content"], L>>;
+declare const useDictionaryDynamic: <const T extends Dictionary, const K extends DictionaryKeys, const A extends LocalesValues | DictionarySelectorForKey<K> = LocalesValues>(dictionaryLoaders: StrictModeLocaleMap<() => Promise<T>> | QualifiedDynamicLoaderMap, key: K, localeOrSelector?: A) => WithOnChange<DeepTransformContent<T["content"]>>;
 //#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":";;;;;;;;AAgEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,oBAAA,mBACK,UAAA,kBACA,cAAA,kBACA,aAAA,GAAgB,aAAA,EAEhC,iBAAA,EAAmB,mBAAA,OAA0B,OAAA,CAAQ,CAAA,IACrD,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,CAAA,KACR,YAAA,CAAa,oBAAA,CAAqB,CAAA,aAAc,CAAA"}
+{"version":3,"file":"useDictionaryDynamic.d.ts","names":[],"sources":["../../../src/client/useDictionaryDynamic.ts"],"mappings":";;;;;;;;;AA2EA;;;;;;;;;;;cAAa,oBAAA,mBACK,UAAA,kBACA,cAAA,kBACA,aAAA,GAAgB,wBAAA,CAAyB,CAAA,IAAK,aAAA,EAE9D,iBAAA,EACI,mBAAA,OAA0B,OAAA,CAAQ,CAAA,KAClC,yBAAA,EACJ,GAAA,EAAK,CAAA,EACL,gBAAA,GAAmB,CAAA,KAClB,YAAA,CAAa,oBAAA,CAAqB,CAAA"}

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

@@ -1,6 +1,6 @@
 import { DeepTransformContent } from "../plugins.js";
 import { WithOnChange } from "./useDictionary.js";
-import { DictionaryKeys, DictionaryRegistryContent, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionaryRegistryResult, DictionarySelectorForKey, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
 
 //#region src/client/useIntlayer.d.ts
 /**
@@ -8,28 +8,17 @@ import { DictionaryKeys, DictionaryRegistryContent, LocalesValues } from "@intla
  * locale changes via the chainable `.onChange()` method — mirroring the API
  * of `react-intlayer`'s `useIntlayer`.
  *
- * Unlike React (where the hook system automatically re-runs on re-render),
- * vanilla JS has no component lifecycle. The `.onChange()` callback is the
- * explicit equivalent: it is called with fresh content whenever the active
- * locale changes. Use it to patch your DOM or trigger a full re-render.
+ * 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)
+ * - `{ id: 'prod_abc', ...metaFields }` — meta record
+ * - `locale` composes with any selector and overrides the current locale
  *
  * The function returns the current content **directly** (same shape as
- * `getIntlayer(key)`), plus the `.onChange()` helper:
+ * `getIntlayer(key)`), plus the `.onChange()` helper.
  *
- * ```ts
- * // React
- * const content = useIntlayer('app');
- *
- * // Vanilla — identical surface API, opt-in reactivity via .onChange()
- * const content = useIntlayer('app');
- * const content = useIntlayer('app').onChange((c) => render(c));
- * ```
- *
- * For cleanup (e.g. Vite HMR), subscribe via `getIntlayerClient().subscribe()`
- * and hold the returned unsubscribe function.
- *
- * @param key    - Dictionary key registered in your intlayer content files.
- * @param locale - Optional locale override (defaults to the current app locale).
+ * @param key - Dictionary key registered in your intlayer content files.
+ * @param localeOrSelector - Optional locale or selector.
  * @returns The current translated content with an `.onChange()` method.
  *
  * @example
@@ -38,17 +27,11 @@ import { DictionaryKeys, DictionaryRegistryContent, LocalesValues } from "@intla
  *
  * installIntlayer();
  *
- * // Static read (no subscription)
  * const content = useIntlayer('homepage');
- * document.querySelector('h1').textContent = String(content.title);
- *
- * // Reactive read — onChange is called on every locale change
- * useIntlayer('homepage').onChange((c) => {
- *   document.querySelector('h1').textContent = String(c.title);
- * });
+ * const faq2 = useIntlayer('faq', { item: 2 });
  * ```
  */
-declare const useIntlayer: <const T extends DictionaryKeys>(key: T, locale?: LocalesValues) => WithOnChange<DeepTransformContent<DictionaryRegistryContent<T>>>;
+declare const useIntlayer: <const T extends DictionaryKeys, const A extends LocalesValues | DictionarySelectorForKey<T> = DeclaredLocales>(key: T, localeOrSelector?: A) => WithOnChange<DeepTransformContent<DictionaryRegistryResult<T, A>, 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":";;;;;;;AAuDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,WAAA,mBAA+B,cAAA,EAC1C,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,aAAA,KACR,YAAA,CAAa,oBAAA,CAAqB,yBAAA,CAA0B,CAAA"}
+{"version":3,"file":"useIntlayer.d.ts","names":[],"sources":["../../../src/client/useIntlayer.ts"],"mappings":";;;;;;;AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,WAAA,mBACK,cAAA,kBACA,aAAA,GAAgB,wBAAA,CAAyB,CAAA,IAAK,eAAA,EAE9D,GAAA,EAAK,CAAA,EACL,gBAAA,GAAmB,CAAA,KAClB,YAAA,CACD,oBAAA,CAAqB,wBAAA,CAAyB,CAAA,EAAG,CAAA,GAAI,qBAAA,CAAsB,CAAA"}

package/dist/types/getDictionary.d.ts

@@ -1,9 +1,14 @@
 import { DeepTransformContent } from "./plugins.js";
-import { DeclaredLocales, LocalesValues } from "@intlayer/types/module_augmentation";
-import { Dictionary } from "@intlayer/types/dictionary";
+import { DeclaredLocales, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
+import { Dictionary, DictionarySelectorForGroup, QualifiedDictionaryGroup, ResolveQualifiedDictionaryContent } from "@intlayer/types/dictionary";
 
 //#region src/getDictionary.d.ts
-declare const getDictionary: <const T extends Dictionary, const L extends LocalesValues = DeclaredLocales>(dictionary: T, locale?: L) => DeepTransformContent<T["content"], L>;
+/**
+ * Transforms a dictionary (or qualified dictionary group) and returns its
+ * content for the given locale or selector (`{ item }`, `{ variant }`,
+ * `{ id, ...meta }`, 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>>;
 //#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":";;;;;cAQa,aAAA,mBACK,UAAA,kBACA,aAAA,GAAgB,eAAA,EAEhC,UAAA,EAAY,CAAA,EACZ,MAAA,GAAS,CAAA,KACR,oBAAA,CAAqB,CAAA,aAAc,CAAA"}
+{"version":3,"file":"getDictionary.d.ts","names":[],"sources":["../../src/getDictionary.ts"],"mappings":";;;;;;;AAoBA;;;cAAa,aAAA,mBACK,UAAA,GAAa,wBAAA,kBAEzB,aAAA,GACA,0BAAA,CAA2B,CAAA,IAAK,eAAA,EAEpC,UAAA,EAAY,CAAA,EACZ,gBAAA,GAAmB,CAAA,KAClB,oBAAA,CACD,iCAAA,CAAkC,CAAA,EAAG,CAAA,GACrC,qBAAA,CAAsB,CAAA"}

package/dist/types/getIntlayer.d.ts

@@ -1,8 +1,13 @@
 import { DeepTransformContent } from "./plugins.js";
-import { DeclaredLocales, DictionaryKeys, DictionaryRegistryContent, LocalesValues } from "@intlayer/types/module_augmentation";
+import { DeclaredLocales, DictionaryKeys, DictionaryRegistryResult, DictionarySelectorForKey, ExtractSelectorLocale, LocalesValues } from "@intlayer/types/module_augmentation";
 
 //#region src/getIntlayer.d.ts
-declare const getIntlayer: <const T extends DictionaryKeys, const L extends LocalesValues = DeclaredLocales>(key: T, locale?: L) => DeepTransformContent<DictionaryRegistryContent<T>, L>;
+/**
+ * Picks one dictionary by its key and returns its content for the given
+ * locale or selector (`{ item }`, `{ variant }`, `{ id, ...meta }`,
+ * 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>>;
 //#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":";;;;cASa,WAAA,mBACK,cAAA,kBACA,aAAA,GAAgB,eAAA,EAEhC,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,CAAA,KACR,oBAAA,CAAqB,yBAAA,CAA0B,CAAA,GAAI,CAAA"}
+{"version":3,"file":"getIntlayer.d.ts","names":[],"sources":["../../src/getIntlayer.ts"],"mappings":";;;;;;AAiBA;;;cAAa,WAAA,mBACK,cAAA,kBACA,aAAA,GAAgB,wBAAA,CAAyB,CAAA,IAAK,eAAA,EAE9D,GAAA,EAAK,CAAA,EACL,gBAAA,GAAmB,CAAA,KAClB,oBAAA,CACD,wBAAA,CAAyB,CAAA,EAAG,CAAA,GAC5B,qBAAA,CAAsB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-intlayer",
-  "version": "8.12.4",
+  "version": "9.0.0-canary.0",
   "private": false,
   "description": "Easily internationalize i18n your Vanilla JS, HTML, and PHP applications with type-safe multilingual content management.",
   "keywords": [
@@ -101,14 +101,14 @@
     "typecheck": "tsc --noEmit --project tsconfig.types.json"
   },
   "dependencies": {
-    "@intlayer/api": "8.12.4",
-    "@intlayer/config": "8.12.4",
-    "@intlayer/core": "8.12.4",
-    "@intlayer/editor": "8.12.4",
-    "@intlayer/types": "8.12.4"
+    "@intlayer/api": "9.0.0-canary.0",
+    "@intlayer/config": "9.0.0-canary.0",
+    "@intlayer/core": "9.0.0-canary.0",
+    "@intlayer/editor": "9.0.0-canary.0",
+    "@intlayer/types": "9.0.0-canary.0"
   },
   "devDependencies": {
-    "@types/node": "25.9.2",
+    "@types/node": "25.9.3",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
     "@utils/tsdown-config": "1.0.4",
@@ -118,7 +118,7 @@
     "vitest": "4.1.8"
   },
   "peerDependencies": {
-    "intlayer": "8.12.4"
+    "intlayer": "9.0.0-canary.0"
   },
   "peerDependenciesMeta": {
     "intlayer": {