@okta/odyssey-react-mui 1.53.0 → 1.55.0

package/src/getTranslationServices.tsx

@@ -0,0 +1,288 @@
+import type { UseTranslationOptions as UseI18NextTranslationOptions } from "react-i18next";
+
+import i18n, { createInstance, TOptions } from "i18next";
+import { memo, ReactElement, ReactNode, useEffect } from "react";
+import {
+  I18nextProvider,
+  initReactI18next,
+  Trans as TransI18nNext,
+  TransProps as TransI18nNextProps,
+  useTranslation as useI18nNextTranslation,
+} from "react-i18next";
+
+import type { DefaultSupportedLanguages } from "./translationServices.types.js";
+
+import { getTypedObjectEntries } from "./getTypedObjectEntries.js";
+
+/** A record of translation keys and their corresponding translated strings. */
+export type I18nTranslationBundle = Record<string, string>;
+
+/** A record of language codes and their corresponding translation bundles. */
+export type ResourcesRecord = Record<string, I18nTranslationBundle>;
+
+/**
+ * Props for the `getTranslationServices` function.
+ * It infers the supported language codes and bundle types from the `resources` object.
+ */
+export type GetTranslationServicesProps<
+  TNamespace extends string,
+  TResources extends ResourcesRecord,
+  TDefaultLanguageCode extends Extract<keyof TResources, string>,
+> = {
+  /**
+   * Default language code to fall back to.
+   * MUST be one of the keys in the `resources` object.
+   */
+  defaultLanguageCode: TDefaultLanguageCode;
+  /** The namespace for the translation resources. */
+  namespace: TNamespace;
+  /** The resources object, from which all language codes and bundle types are inferred. */
+  resources: TResources;
+};
+
+export type TranslationOverrides<
+  SupportedLanguageCodes extends string = DefaultSupportedLanguages,
+> = Record<SupportedLanguageCodes, Partial<I18nTranslationBundle>>;
+
+export type TranslationProviderProps<
+  SupportedLanguageCodes extends string = DefaultSupportedLanguages,
+> = {
+  children: ReactNode;
+  languageCode?: SupportedLanguageCodes;
+  translationOverrides?: TranslationOverrides<SupportedLanguageCodes>;
+};
+
+type ExtractPlaceholders<TString extends string> =
+  TString extends `${string}{{${infer PlaceholderId}}}${infer Rest}`
+    ? PlaceholderId | ExtractPlaceholders<Rest>
+    : never;
+
+export type PlaceholderValues =
+  | string
+  | number
+  | TemplateStringsArray
+  | (string | TemplateStringsArray)[];
+
+export type PlaceholderRecord<
+  TResourceBundle extends I18nTranslationBundle,
+  TKey extends keyof TResourceBundle & string,
+> = Record<ExtractPlaceholders<TResourceBundle[TKey]>, PlaceholderValues>;
+
+/**
+ * Custom function signature that enforces strong typing
+ * against the keys of a specific resource bundle.
+ */
+export type TypedTFunction<TResourceBundle extends I18nTranslationBundle> = <
+  TKey extends keyof TResourceBundle & string,
+>(
+  key: TKey | TKey[],
+  ...options: TKey extends keyof TResourceBundle
+    ? // key exists in the resource bundle, we check for placeholders
+      [ExtractPlaceholders<TResourceBundle[TKey]>] extends [never]
+      ? [options?: TOptions] // no placeholders, options are optional
+      : [options: TOptions<PlaceholderRecord<TResourceBundle, TKey>>] // placeholders exist, placeholder values are required
+    : // key does not exist in the resource bundle
+      [never]
+) => string;
+
+/**
+ * Return type of our strongly-typed `useTranslation` hook.
+ *
+ * Matches the original `useTranslation` return type, but with
+ * our `TypedTFunction` rather than the generic `TFunction`.
+ */
+export type TypedUseTranslationResponse<
+  TResourceBundle extends I18nTranslationBundle,
+> = [t: TypedTFunction<TResourceBundle>, i18n: typeof i18n, ready: boolean] & {
+  i18n: typeof i18n;
+  ready: boolean;
+  t: TypedTFunction<TResourceBundle>;
+};
+
+export interface IGenericTranslationProvider {
+  <SupportedLanguageCodes extends string = DefaultSupportedLanguages>(
+    props: TranslationProviderProps<SupportedLanguageCodes>,
+  ): ReactNode;
+}
+
+export type UseTranslationOptions<TNamespace extends string> = Omit<
+  UseI18NextTranslationOptions<TNamespace>,
+  "i18n"
+>;
+
+/**
+ * A strongly-typed version of the `useTranslation` hook from `react-i18next`,
+ * bound to a specific namespace and resource bundle type.
+ */
+export type UseTranslation<
+  TNamespace extends string,
+  TResourceBundle extends I18nTranslationBundle,
+> = (
+  options?: UseTranslationOptions<TNamespace>,
+) => TypedUseTranslationResponse<TResourceBundle>;
+
+export type TypedTrans<
+  TNamespace extends string,
+  TResourceBundle extends I18nTranslationBundle,
+> = <TKey extends Extract<keyof TResourceBundle, string>>(
+  props: Omit<
+    TransI18nNextProps<TKey & string, TNamespace>,
+    "i18n" | "values" | "i18nKey"
+  > & {
+    // explicitly type `i18nKey` to be the specific key
+    i18nKey: TKey | TKey[];
+  } & ([ExtractPlaceholders<TResourceBundle[TKey]>] extends [never] // add conditional `values` prop
+      ? // if no placeholders, `values` is forbidden
+        { values?: never }
+      : // if placeholders exist, `values` is required and strictly typed
+        {
+          values: PlaceholderRecord<TResourceBundle, TKey>;
+        }),
+) => ReactElement;
+
+export type TranslationServices<
+  TNamespace extends string,
+  TResources extends ResourcesRecord,
+  TDefaultLanguageCode extends Extract<keyof TResources, string>,
+> = {
+  /** The i18next instance created for this package. */
+  i18n: typeof i18n;
+  Trans: TypedTrans<TNamespace, TResources[TDefaultLanguageCode]>;
+  /**
+   * A ready-to-use Translation Provider, which is a generic component.
+   *
+   * The consumer can specify the supported languages when using it.
+   * @example <TranslationProvider<"en" | "ja">>
+   */
+  TranslationProvider: IGenericTranslationProvider;
+  /** A pre-typed `useTranslation` hook bound to the given namespace. */
+  useTranslation: UseTranslation<TNamespace, TResources[TDefaultLanguageCode]>;
+};
+
+/**
+ * Initializes an `i18next` instance and provides strongly-typed
+ * translation utilities: `useTranslation`, `Trans`, and `TranslationProvider`.
+ */
+export function getTranslationServices<
+  TNamespace extends string,
+  TResources extends ResourcesRecord,
+  TDefaultLanguageCode extends Extract<keyof TResources, string>,
+>({
+  defaultLanguageCode,
+  namespace,
+  resources,
+}: GetTranslationServicesProps<
+  TNamespace,
+  TResources,
+  TDefaultLanguageCode
+>): TranslationServices<TNamespace, TResources, TDefaultLanguageCode> {
+  const i18nInstance = createInstance();
+
+  i18nInstance
+    .use(initReactI18next)
+    .init({
+      defaultNS: namespace,
+      ns: [namespace],
+      fallbackLng: defaultLanguageCode,
+      load: "currentOnly",
+      keySeparator: false,
+      interpolation: {
+        escapeValue: false,
+        skipOnVariables: false,
+      },
+      react: {
+        bindI18nStore: "added",
+        useSuspense: false,
+      },
+    })
+    .catch((error) => {
+      console.error(
+        `[odyssey-contribution-tooling] Error initializing i18nInstance for namespace: ${namespace}`,
+      );
+      console.error(error);
+    });
+
+  Object.entries(resources).forEach(([languageCode, bundle]) => {
+    i18nInstance.addResourceBundle(languageCode, namespace, bundle);
+  });
+
+  const TranslationProvider = <
+    ProviderSupportedLanguageCodes extends string = DefaultSupportedLanguages,
+  >({
+    children,
+    languageCode,
+    translationOverrides,
+  }: TranslationProviderProps<ProviderSupportedLanguageCodes>) => {
+    useEffect(() => {
+      const updatedLanguageCode = languageCode || window.navigator.language;
+      i18nInstance.changeLanguage(updatedLanguageCode).catch((error) => {
+        console.error(
+          `[odyssey-contribution-tooling] Error changing language code in i18nInstance to: ${updatedLanguageCode}`,
+        );
+        console.error(error);
+      });
+    }, [languageCode]);
+
+    useEffect(() => {
+      if (translationOverrides) {
+        getTypedObjectEntries(translationOverrides).forEach(
+          ([languageCode, overrideBundle]) => {
+            i18nInstance.addResourceBundle(
+              languageCode,
+              namespace,
+              overrideBundle,
+              true,
+              true,
+            );
+          },
+        );
+      }
+    }, [translationOverrides]);
+
+    return <I18nextProvider i18n={i18nInstance}>{children}</I18nextProvider>;
+  };
+
+  const MemoizedTranslationProvider = memo(TranslationProvider);
+  MemoizedTranslationProvider.displayName = "TranslationProvider";
+
+  const Trans: TypedTrans<TNamespace, TResources[TDefaultLanguageCode]> = (
+    props,
+  ) => {
+    return (
+      <TransI18nNext
+        {...(props satisfies TransI18nNextProps<string, TNamespace>)}
+        i18n={i18nInstance}
+      />
+    );
+  };
+
+  const useTranslation: UseTranslation<
+    TNamespace,
+    TResources[TDefaultLanguageCode]
+  > = (options?: UseTranslationOptions<TNamespace>) => {
+    const [t, i18n, ready] = useI18nNextTranslation(namespace, {
+      ...options,
+      i18n: i18nInstance,
+    });
+    const typedT = t as unknown as TypedTFunction<
+      TResources[TDefaultLanguageCode]
+    >;
+
+    const result = [typedT, i18n, ready] as TypedUseTranslationResponse<
+      TResources[TDefaultLanguageCode]
+    >;
+
+    result.t = typedT;
+    result.i18n = i18n;
+    result.ready = ready;
+
+    return result;
+  };
+
+  return {
+    i18n: i18nInstance,
+    TranslationProvider: MemoizedTranslationProvider,
+    Trans,
+    useTranslation,
+  };
+}

package/src/getTypedObjectEntries.ts

@@ -0,0 +1,3 @@
+export const getTypedObjectEntries = <ObjectType extends object>(
+  obj: ObjectType,
+) => Object.entries(obj) as [keyof ObjectType, ObjectType[keyof ObjectType]][];

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./getTranslationServices.js";
+export * from "./translationServices.types.js";

package/src/translationServices.types.ts

@@ -0,0 +1,36 @@
+export const defaultSupportedLanguages = [
+  "cs", // Czech
+  "da", // Danish
+  "de", // German
+  "el", // Greek
+  "en", // English
+  "es", // Spanish
+  "eu", // Euskara
+  "fi", // Finnish
+  "fr", // French
+  "ht", // Haitian Creole
+  "hu", // Hungarian
+  "id", // Indonesian
+  "it", // Italian
+  "ja", // Japanese
+  "ko", // Korean
+  "ms", // Malaysian
+  "nb", // Norwegian
+  "nl_NL", // Dutch
+  "ok_PL", // (Test Language) Pseudo-loc
+  "ok_SK", // (Test Language) Show Keys
+  "pl", // Polish
+  "pt_BR", // Portuguese (Brazil)
+  "ro", // Romanian
+  "ru", // Russian
+  "sv", // Swedish
+  "th", // Thai
+  "tr", // Turkish
+  "uk", // Ukrainian
+  "vi", // Vietnamese
+  "zh_CN", // Chinese (PRC)
+  "zh_TW", // Chinese
+] as const;
+
+export type DefaultSupportedLanguages =
+  (typeof defaultSupportedLanguages)[number];

package/src/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "composite": true
+  },
+  "include": ["**/*"],
+  "extends": "../tsconfig.json"
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "allowJs": false,
+    "composite": true,
+    "emitDeclarationOnly": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@emotion/react",
+    "lib": ["DOM", "ESNext", "ES2021"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": false,
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "outDir": "dist/types",
+    "resolveJsonModule": true,
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2020",
+    "types": ["@vitest/browser/matchers", "vitest/globals"]
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "../vite.config.ts",
+    "../vite.config.project.ts",
+    "../vitest.config.ts",
+    "../vitest.config.project.ts"
+  ],
+  "exclude": ["**/dist/**/*"]
+}

package/vite.config.project.ts

@@ -0,0 +1,61 @@
+/*!
+ * Copyright (c) 2025-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { defineConfig } from "vite";
+
+import packageJson from "./package.json" with { type: "json" };
+
+const umdName = packageJson.name
+  .replace(/^(@(.+)\/)?(.+)$/, "$2-$3")
+  .split("-")
+  .map((namePart) =>
+    namePart.slice(0, 1).toUpperCase().concat(namePart.slice(1)),
+  )
+  .join("");
+
+// Vite customizations can go in this file. These will override those provided by the stack.
+export default defineConfig(({ command }) => ({
+  define:
+    command === "build"
+      ? {
+          "process.env.NODE_ENV": '"production"',
+        }
+      : {},
+
+  build: {
+    emptyOutDir: false,
+    lib: {
+      entry: `${__dirname}/src/index.ts`,
+      fileName: (format) =>
+        `index.${format}.${format === "umd" ? "cjs" : "js"}`,
+      formats: ["es", "iife", "umd"],
+      name: umdName,
+    },
+    sourcemap: true,
+    rollupOptions: {
+      external: [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime",
+      ],
+      output: {
+        globals: {
+          react: "React",
+          "react-dom": "ReactDOM",
+          "react/jsx-runtime": "ReactJSXRuntime",
+          "react/jsx-dev-runtime": "ReactJSXDevRuntime",
+        },
+      },
+    },
+  },
+}));

package/vite.config.ts

@@ -0,0 +1,21 @@
+// DO NOT EDIT THIS FILE!
+// This is the vite.config.ts file provided by the core-gen4 stack. Do not edit this; instead, place any custom configuration settings
+// in the `vite.config.project.ts` file. If this file is modified, you are on your own and results of using the stack's vite config
+// cannot be supported.
+
+import stackConfig from "@okta/ui-stacks-component-libraries-odyssey-contributions/dist/configs/vite.config.js";
+import { defineConfig, mergeConfig, type UserConfigFnPromise } from "vite";
+
+import projectConfig from "./vite.config.project.js";
+
+// Merge, in this order:
+// - the stack's vite.config.js
+// - the project's vite.config.project.js
+export default defineConfig(async (env) =>
+  mergeConfig(
+    stackConfig,
+    typeof projectConfig === "function"
+      ? await (projectConfig as UserConfigFnPromise)(env)
+      : projectConfig,
+  ),
+);

package/vite.config.ts.bak

@@ -0,0 +1,33 @@
+/*!
+ * Copyright (c) 2025-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+// DO NOT EDIT THIS FILE!
+// This is the vite.config.ts file provided by the core-gen4 stack. Do not edit this; instead, place any custom configuration settings
+// in the `vite.config.project.ts` file. If this file is modified, you are on your own and results of using the stack's vite config
+// cannot be supported.
+
+import stackConfig from "@okta/ui-stacks-component-libraries-odyssey-contributions/dist/configs/vite.config.js";
+import { defineConfig, mergeConfig, type UserConfigFnPromise } from "vite";
+
+import projectConfig from "./vite.config.project.js";
+
+// Merge, in this order:
+// - the stack's vite.config.js
+// - the project's vite.config.project.js
+export default defineConfig(async (env) =>
+  mergeConfig(
+    stackConfig,
+    typeof projectConfig === "function"
+      ? await (projectConfig as UserConfigFnPromise)(env)
+      : projectConfig,
+  ),
+);

package/vitest-browser-setup.ts

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import "@testing-library/jest-dom/vitest";
+import "jest-axe/extend-expect";

package/vitest-jsdom-setup.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) 2025-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import "@testing-library/jest-dom/vitest";

package/vitest-node-setup.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import "regenerator-runtime/runtime";

package/vitest.config.project.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) 2025-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { defineConfig } from "vitest/config";
+
+// Vitest customizations can go in this file. These will override those provided by the stack.
+export default defineConfig({});

package/vitest.config.ts

@@ -0,0 +1,27 @@
+// DO NOT EDIT THIS FILE!
+// This is the vitest.config.ts file provided by the core-gen4 stack. Do not edit this; instead, place any custom configuration settings
+// in the `vitest.config.project.ts` file. If this file is modified, you are on your own and results of using the stack's vitest config
+// cannot be supported.
+
+import stackTestConfig from "@okta/ui-stacks-component-libraries-odyssey-contributions/dist/configs/vitest.config.js";
+import { defineConfig, mergeConfig } from "vite";
+import { type UserConfigFnPromise } from "vitest/config";
+
+import viteConfig from "./vite.config.js";
+import projectTestConfig from "./vitest.config.project.js";
+
+// Merge, in this order:
+// - the project's vite.config.js
+// - the stack's vitest.config.js
+// - the project's vitest.config.project.js
+export default defineConfig(async (env) =>
+  mergeConfig(
+    mergeConfig(
+      typeof viteConfig === "function" ? await viteConfig(env) : viteConfig,
+      stackTestConfig,
+    ),
+    typeof projectTestConfig === "function"
+      ? await (projectTestConfig as UserConfigFnPromise)(env)
+      : projectTestConfig,
+  ),
+);

package/vitest.config.ts.bak

@@ -0,0 +1,27 @@
+// DO NOT EDIT THIS FILE!
+// This is the vitest.config.ts file provided by the core-gen4 stack. Do not edit this; instead, place any custom configuration settings
+// in the `vitest.config.project.ts` file. If this file is modified, you are on your own and results of using the stack's vitest config
+// cannot be supported.
+
+import stackTestConfig from "@okta/ui-stacks-component-libraries-odyssey-contributions/dist/configs/vitest.config.js";
+import { defineConfig, mergeConfig } from "vite";
+import { type UserConfigFnPromise } from "vitest/config";
+
+import viteConfig from "./vite.config.js";
+import projectTestConfig from "./vitest.config.project.js";
+
+// Merge, in this order:
+// - the project's vite.config.js
+// - the stack's vitest.config.js
+// - the project's vitest.config.project.js
+export default defineConfig(async (env) =>
+  mergeConfig(
+    mergeConfig(
+      typeof viteConfig === "function" ? await viteConfig(env) : viteConfig,
+      stackTestConfig,
+    ),
+    typeof projectTestConfig === "function"
+      ? await (projectTestConfig as UserConfigFnPromise)(env)
+      : projectTestConfig,
+  ),
+);