@hitachivantara/app-shell-shared 2.2.5 → 2.3.0

package/dist/AppShellRuntimeContext.js

@@ -1,5 +1,15 @@
-import { createContext } from "react";
+import { createContext, useContext } from "react";
 const HvAppShellRuntimeContext = createContext(void 0);
+const useHvAppShellRuntimeContext = () => {
+  const context = useContext(HvAppShellRuntimeContext);
+  if (!context) {
+    throw new Error(
+      "useHvAppShellRuntimeContext must be used within HvAppShellRuntimeContext.Provider"
+    );
+  }
+  return context;
+};
 export {
-  HvAppShellRuntimeContext
+  HvAppShellRuntimeContext,
+  useHvAppShellRuntimeContext
 };

package/dist/bundles/app-shell-shared.esm.js

@@ -17,13 +17,32 @@ const useHvAppShellModel = () => {
 };
 const HvAppShellViewContext = createContext(void 0);
 const HvAppShellRuntimeContext = createContext(void 0);
+const useHvAppShellRuntimeContext = () => {
+  const context = useContext(HvAppShellRuntimeContext);
+  if (!context) {
+    throw new Error(
+      "useHvAppShellRuntimeContext must be used within HvAppShellRuntimeContext.Provider"
+    );
+  }
+  return context;
+};
 const HvAppShellCombinedProvidersContext = createContext(void 0);
 const useHvAppShellCombinedProviders = () => {
   return useContext(
     HvAppShellCombinedProvidersContext
   );
 };
-const CONFIG_TRANSLATIONS_NAMESPACE = "configTranslations";
+const CONFIG_TRANSLATIONS_NAMESPACE = "app";
+const HvAppShellI18nContext = createContext(void 0);
+const useHvAppShellI18n = () => {
+  const context = useContext(HvAppShellI18nContext);
+  if (!context) {
+    throw new Error(
+      "useHvAppShellI18n must be used within HvAppShellI18nContext.Provider"
+    );
+  }
+  return context;
+};
 const getMenuTargetHref = (menuItem) => {
   const { target } = menuItem;
   if (target) {
@@ -171,11 +190,12 @@ const MAX_TOP_MENU_DEPTH = 2;
 const useHvMenuItems = () => {
   const { pathname, search, state: locationState } = useLocation();
   const { navigationMode, menu } = useHvAppShellModel();
-  const { i18n } = useContext(HvAppShellRuntimeContext) ?? {};
+  useHvAppShellI18n();
+  const { i18n } = useHvAppShellRuntimeContext();
+  const resolvedLanguage = i18n.resolvedLanguage;
   const tConfig = useMemo(
-    () => i18n?.getFixedT(i18n.language, CONFIG_TRANSLATIONS_NAMESPACE) ?? // should not happen, but fallback if the i18n instance is not available
-    ((l) => l),
-    [i18n]
+    () => i18n.getFixedT(resolvedLanguage ?? null, CONFIG_TRANSLATIONS_NAMESPACE),
+    [i18n, resolvedLanguage]
   );
   const items = useMemo(() => {
     const menuItemsDepth = navigationMode === "ONLY_TOP" ? MAX_TOP_MENU_DEPTH : void 0;
@@ -268,12 +288,15 @@ export {
   DynamicHooksEvaluator,
   HvAppShellCombinedProvidersContext,
   HvAppShellContext,
+  HvAppShellI18nContext,
   HvAppShellModelContext,
   HvAppShellRuntimeContext,
   HvAppShellViewContext,
   useAsync,
   useHvAppShellCombinedProviders,
   useHvAppShellConfig,
+  useHvAppShellI18n,
   useHvAppShellModel,
+  useHvAppShellRuntimeContext,
   useHvMenuItems
 };

package/dist/hooks/useMenuItems.js

@@ -1,18 +1,19 @@
-import { useContext, useMemo, useState, useEffect } from "react";
+import { useMemo, useState, useEffect } from "react";
 import { useLocation } from "react-router-dom";
 import { useHvAppShellModel } from "../AppShellModelContext.js";
-import { HvAppShellRuntimeContext } from "../AppShellRuntimeContext.js";
-import { CONFIG_TRANSLATIONS_NAMESPACE } from "../i18n/index.js";
+import { useHvAppShellRuntimeContext } from "../AppShellRuntimeContext.js";
+import { useHvAppShellI18n, CONFIG_TRANSLATIONS_NAMESPACE } from "../i18n/index.js";
 import { createMenuItems, searchHrefInMenuItems, addPrefixToHref, getRootIdFromItemId, findItemById, findFirstLeafItem } from "../utils/navigationUtils.js";
 const MAX_TOP_MENU_DEPTH = 2;
 const useHvMenuItems = () => {
   const { pathname, search, state: locationState } = useLocation();
   const { navigationMode, menu } = useHvAppShellModel();
-  const { i18n } = useContext(HvAppShellRuntimeContext) ?? {};
+  useHvAppShellI18n();
+  const { i18n } = useHvAppShellRuntimeContext();
+  const resolvedLanguage = i18n.resolvedLanguage;
   const tConfig = useMemo(
-    () => i18n?.getFixedT(i18n.language, CONFIG_TRANSLATIONS_NAMESPACE) ?? // should not happen, but fallback if the i18n instance is not available
-    ((l) => l),
-    [i18n]
+    () => i18n.getFixedT(resolvedLanguage ?? null, CONFIG_TRANSLATIONS_NAMESPACE),
+    [i18n, resolvedLanguage]
   );
   const items = useMemo(() => {
     const menuItemsDepth = navigationMode === "ONLY_TOP" ? MAX_TOP_MENU_DEPTH : void 0;

package/dist/i18n/index.js

@@ -1,4 +1,17 @@
-const CONFIG_TRANSLATIONS_NAMESPACE = "configTranslations";
+import { createContext, useContext } from "react";
+const CONFIG_TRANSLATIONS_NAMESPACE = "app";
+const HvAppShellI18nContext = createContext(void 0);
+const useHvAppShellI18n = () => {
+  const context = useContext(HvAppShellI18nContext);
+  if (!context) {
+    throw new Error(
+      "useHvAppShellI18n must be used within HvAppShellI18nContext.Provider"
+    );
+  }
+  return context;
+};
 export {
-  CONFIG_TRANSLATIONS_NAMESPACE
+  CONFIG_TRANSLATIONS_NAMESPACE,
+  HvAppShellI18nContext,
+  useHvAppShellI18n
 };

package/dist/index.d.ts

@@ -13,7 +13,7 @@ import { useAsync } from '@hitachivantara/app-shell-services';
 
 export { AsyncResult }
 
-export declare const CONFIG_TRANSLATIONS_NAMESPACE = "configTranslations";
+export declare const CONFIG_TRANSLATIONS_NAMESPACE = "app";
 
 export declare const DynamicHooksEvaluator: <THook extends (...args: any[]) => TResult, TResult = ReturnType<THook>>({ hooks, onEvaluate, }: DynamicHooksEvaluatorProps<THook, TResult>) => FunctionComponentElement<DynamicHooksEvaluatorProps<THook, TResult>>;
 
@@ -72,6 +72,27 @@ export declare interface HvAppShellConfig {
     apps?: Record<string, string>;
     menu?: HvAppShellMenuConfig[];
     translations?: Record<string, object>;
+    /**
+     * Base URL for loading translation files via HTTP.
+     *
+     * Resolved relative to:
+     * - `configUrl` (when the config was loaded from a URL), or
+     * - the configured `baseUrl` of the App Shell (including its default).
+     *
+     * The full path composed internally is:
+     *   `{translationsBaseUrl}/locales/{{lng}}/{{ns}}.json`
+     *
+     * Defaults to `"./"`.
+     *
+     * Can coexist with `translations`, which provides pre-loaded resources.
+     * When both are provided, `translations` are shown immediately and then
+     * refreshed when the HTTP backend responds.
+     *
+     * Set to `false` to disable HTTP-based translation loading entirely.
+     * Useful when only inline `translations` are used and the extra network
+     * requests would cause 404 errors in legacy setups.
+     */
+    translationsBaseUrl?: string | false;
     navigationMode?: "TOP_AND_LEFT" | "ONLY_TOP" | "ONLY_LEFT";
     mainPanel?: HvAppShellMainPanelConfig;
     theming?: HvAppShellThemingConfig;
@@ -106,8 +127,24 @@ export declare interface HvAppShellHelp {
     description?: string;
 }
 
+export declare const HvAppShellI18nContext: Context<HvAppShellI18nContextValue | undefined>;
+
+/**
+ * The App Shell I18N context.
+ */
+export declare type HvAppShellI18nContextValue = {
+    /**
+     * Gets the current language of the App Shell, as a BCP 47 language tag.
+     */
+    language: string;
+    /**
+     * Sets the App Shell's current language.
+     */
+    changeLanguage: (newLng?: string) => Promise<void>;
+};
+
 export declare interface HvAppShellIcon {
-    iconType: "uikit";
+    iconType: "uikit" | "unocss";
     name: string;
 }
 
@@ -170,6 +207,36 @@ export declare interface HvAppShellProvidersModel extends HvAppShellConditionalM
 
 export declare const HvAppShellRuntimeContext: Context<HvAppShellRuntimeContextValue | undefined>;
 
+/**
+ * Context for providing runtime information and utilities to the App Shell.
+ * This context supports the App Shell's internal operations and should not be used outside.
+ *
+ * Currently, exposes the I18next instance that the App Shell internal modules should use for translations.
+ *
+ * The reason this is needed, and that the I18next instance installed via `I18nextProvider` by
+ * `AppShellContainer` is that the App Shell UI and associated packages is typically compiled
+ * together with other custom code, using the App Shell vite plugin. Hence, the I18next library
+ * is  shared with the custom code. If the custom code installs its own I18next instance at a
+ * high enough level in the component tree, for example, inside a global or (even wider impact)
+ * system provider, all the internal App Shell UI components beneath it would no longer be guaranteed
+ * to access the original, root I18next instance.
+ *
+ * To use I18next properly from within the App Shell internal code, do, for example:
+ * ```ts
+ * const { i18n } = useHvAppShellRuntimeContext();
+ * const { t } = useTranslation(ns, {i18n});
+ * ```
+ *
+ * The current package, `app-shell-shared`, is a special case as it cannot depend on `i18next` at runtime (only
+ * i18next types which are removed when compiling to JS can be referenced). See how {@link useHvMenuItems} handles this.
+ *
+ * The custom App Shell ultimately compiling the code should not use the root I18next provider.
+ * It may not be configured as needed by external code. It can however, have its own I18next instance, which can/should
+ * be configured for the same resource bundle repository (of `./locales/{{lng}}/{{ns}}.json`), rooted at the configured
+ * translations base path via {@link HvAppShellConfig#translationsBaseUrl}, albeit consuming other namespaces.
+ * This repository is required when providing translations outside the App Shell configuration (i.e., not embedded in
+ * the configuration via {@link HvAppShellConfig#translations}).
+ */
 export declare interface HvAppShellRuntimeContextValue {
     i18n: i18n;
 }
@@ -247,8 +314,15 @@ export declare const useHvAppShellCombinedProviders: () => HvAppShellCombinedPro
 
 export declare const useHvAppShellConfig: () => HvAppShellContextValue;
 
+/**
+ * Gets the App Shell's I18N context.
+ */
+export declare const useHvAppShellI18n: () => HvAppShellI18nContextValue;
+
 export declare const useHvAppShellModel: () => HvAppShellModel;
 
+export declare const useHvAppShellRuntimeContext: () => HvAppShellRuntimeContextValue;
+
 export declare const useHvMenuItems: () => MenuItemsContext;
 
 export declare interface ViewHvContainerProps extends Omit<HvContainerProps, "children"> {

package/dist/index.js

@@ -1,10 +1,10 @@
 import { HvAppShellContext, useHvAppShellConfig } from "./AppShellContext.js";
 import { HvAppShellModelContext, useHvAppShellModel } from "./AppShellModelContext.js";
 import { HvAppShellViewContext } from "./AppShellViewContext.js";
-import { HvAppShellRuntimeContext } from "./AppShellRuntimeContext.js";
+import { HvAppShellRuntimeContext, useHvAppShellRuntimeContext } from "./AppShellRuntimeContext.js";
 import { HvAppShellCombinedProvidersContext, useHvAppShellCombinedProviders } from "./AppShellCombinedProvidersContext.js";
 import { useAsync } from "@hitachivantara/app-shell-services";
-import { CONFIG_TRANSLATIONS_NAMESPACE } from "./i18n/index.js";
+import { CONFIG_TRANSLATIONS_NAMESPACE, HvAppShellI18nContext, useHvAppShellI18n } from "./i18n/index.js";
 import { useHvMenuItems } from "./hooks/useMenuItems.js";
 import { DynamicHooksEvaluator } from "./components/DynamicHooksEvaluator/DynamicHooksEvaluator.js";
 export {
@@ -12,12 +12,15 @@ export {
   DynamicHooksEvaluator,
   HvAppShellCombinedProvidersContext,
   HvAppShellContext,
+  HvAppShellI18nContext,
   HvAppShellModelContext,
   HvAppShellRuntimeContext,
   HvAppShellViewContext,
   useAsync,
   useHvAppShellCombinedProviders,
   useHvAppShellConfig,
+  useHvAppShellI18n,
   useHvAppShellModel,
+  useHvAppShellRuntimeContext,
   useHvMenuItems
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitachivantara/app-shell-shared",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "type": "module",
   "private": false,
   "author": "Hitachi Vantara UI Kit Team",
@@ -22,7 +22,7 @@
     "react-router-dom": "^6.9.0"
   },
   "optionalDependencies": {
-    "@hitachivantara/uikit-react-core": "^6.8.0"
+    "@hitachivantara/uikit-react-core": "^6.8.1"
   },
   "files": [
     "dist"
@@ -39,7 +39,7 @@
     "access": "public",
     "directory": "package"
   },
-  "gitHead": "f79885f320f5cdf5b438ef8b2e866965c9626ce7",
+  "gitHead": "b9034f709fcfa749a28a52ed31dab060455493d6",
   "types": "./dist/index.d.ts",
   "module": "dist/index.js"
 }