impact-ui 3.7.40-alpha.2 → 3.7.40-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impact-ui",
-  "version": "3.7.40-alpha.2",
+  "version": "3.7.40-alpha.3",
   "description": "Impact Analytics UI library",
   "main": "dist/index.js",
   "files": [

package/src/components/Table/agGridLocale.js

@@ -0,0 +1,95 @@
+import { AGLocaleMap, BASE_LOCALE } from "../../locales/index";
+
+/**
+ * AG Grid bakes these pagination labels into the panel HTML at create time.
+ * Updating localeText/getLocaleText alone will not refresh them — we patch
+ * these keys into the DOM after setAgGridLocaleText().
+ */
+export const AG_GRID_PAGINATION_LOCALE_KEYS = [
+  "page",
+  "to",
+  "of",
+  "firstPage",
+  "previousPage",
+  "nextPage",
+  "lastPage",
+];
+
+export function getAgGridLocaleTextForLocale(locale) {
+  return AGLocaleMap?.[locale] || AGLocaleMap?.[BASE_LOCALE] || {};
+}
+
+/**
+ * Update the mutable key→value object that getLocaleText reads from.
+ * Call this when the app locale changes (instead of remounting the grid).
+ */
+export function setAgGridLocaleText(localeTextRef, locale) {
+  localeTextRef.current = getAgGridLocaleTextForLocale(locale);
+  return localeTextRef.current;
+}
+
+/**
+ * AG Grid getLocaleText callback — looks up one key at a time from the
+ * object managed by setAgGridLocaleText.
+ */
+export function createAgGridGetLocaleText(localeTextRef) {
+  return (params) => {
+    let localisedText = localeTextRef.current?.[params.key];
+
+    if (localisedText == null) {
+      return params.defaultValue;
+    }
+
+    const variableValues = params.variableValues;
+    if (variableValues?.length) {
+      let found = 0;
+      while (found < variableValues.length) {
+        const idx = localisedText.indexOf("${variable}");
+        if (idx === -1) break;
+        localisedText =
+          localisedText.slice(0, idx) +
+          variableValues[found] +
+          localisedText.slice(idx + "${variable}".length);
+        found += 1;
+      }
+    }
+
+    return localisedText;
+  };
+}
+
+/**
+ * Apply the pagination keys from the current localeText object onto the
+ * already-rendered AG Grid paging panel (no grid remount).
+ */
+export function syncAgGridPaginationLocale(container, localeText) {
+  if (!container || !localeText) return;
+
+  container.querySelectorAll(".ag-paging-panel").forEach((panel) => {
+    const setByIdSuffix = (suffix, text) => {
+      if (text == null) return;
+      const el = panel.querySelector(`[id$="-${suffix}"]`);
+      if (el) el.textContent = text;
+    };
+
+    setByIdSuffix("to", localeText.to);
+    setByIdSuffix("of", localeText.of);
+    setByIdSuffix("start-page", localeText.page);
+    setByIdSuffix("of-page", localeText.of);
+
+    const buttons = panel.querySelectorAll(
+      ".ag-paging-page-summary-panel .ag-paging-button"
+    );
+    const buttonLabels = [
+      localeText.firstPage,
+      localeText.previousPage,
+      localeText.nextPage,
+      localeText.lastPage,
+    ];
+    buttons.forEach((button, index) => {
+      if (buttonLabels[index]) {
+        button.setAttribute("aria-label", buttonLabels[index]);
+      }
+    });
+  });
+}

package/src/components/Table/index.js

@@ -39,7 +39,12 @@ import { buildAdvanceSearchFilterModel } from "./filterUtils";
 import BulkActionBar from "./actionBar";
 import AdvanceSortModal from "./AdvanceSortModal";
 import { useTranslation } from "../../i18n";
-import { AGLocaleMap } from "../../locales/index";
+import {
+  createAgGridGetLocaleText,
+  getAgGridLocaleTextForLocale,
+  setAgGridLocaleText,
+  syncAgGridPaginationLocale,
+} from "./agGridLocale";
 
 const TableContent = forwardRef(
   (
@@ -159,6 +164,24 @@ const TableContent = forwardRef(
     );
 
     const { t, locale } = useTranslation();
+    const localeTextRef = useRef(getAgGridLocaleTextForLocale(locale));
+    const getLocaleText = useMemo(
+      () => createAgGridGetLocaleText(localeTextRef),
+      []
+    );
+    const syncPaginationLocale = useCallback(() => {
+      syncAgGridPaginationLocale(
+        document.getElementById(gridId || "myGrid"),
+        localeTextRef.current
+      );
+    }, [gridId]);
+
+    useEffect(() => {
+      setAgGridLocaleText(localeTextRef, locale);
+      const frameId = requestAnimationFrame(syncPaginationLocale);
+      return () => cancelAnimationFrame(frameId);
+    }, [locale, syncPaginationLocale]);
+
     const saveViewCustomFilter = saveViewCustomFilterProp || {
       options: [
         { label: t("table.viewGlobal"), value: "global" },
@@ -698,6 +721,7 @@ const TableContent = forwardRef(
 
     const onFirstDataRendered = (params) => {
       if (params?.api) params.api.getModel().appliedFontSize = tableFontSize;
+      syncPaginationLocale();
       args?.onFirstDataRendered?.(params);
       args?.gridOptions?.onFirstDataRendered?.(params);
     };
@@ -731,9 +755,14 @@ const TableContent = forwardRef(
     const paginationChanged = useCallback(
       (params) => {
         setDynmaicStyleToButtonComponent();
+        syncPaginationLocale();
         onPaginationChanged(params);
       },
-      [setDynmaicStyleToButtonComponent, onPaginationChanged]
+      [
+        setDynmaicStyleToButtonComponent,
+        syncPaginationLocale,
+        onPaginationChanged,
+      ]
     );
 
     useEffect(() => {
@@ -1538,10 +1567,11 @@ const TableContent = forwardRef(
               }`}
             >
               <AgGridReact
-                {...(({ components, ...rest }) => rest)(args)}
+                {...(({ components, localeText, getLocaleText, ...rest }) => rest)(
+                  args
+                )}
                 components={wrappedComponents}
                 ref={actualRef}
-                key={`aggrid-${locale}`}
                 suppressRowTransform={
                   viewPoint === "list" ? false : args?.suppressRowTransform
                 }
@@ -1576,7 +1606,7 @@ const TableContent = forwardRef(
                 getRowClass={getRowClassWrapper}
                 noRowsOverlayComponent={EmptyStateOverlay}
                 onSortChanged={onGridSortChanged}
-                localeText={AGLocaleMap?.[locale]}
+                getLocaleText={getLocaleText}
               />
               {isCommentFeatureEnabled && enableCommentPanel && (
                 <div

package/src/components/TableOld/index.js

@@ -25,7 +25,12 @@ import TableAdvanceSearchModal from "../Table/advanceSearchModal";
 import BulkActionBar from "./actionBar";
 import { ReactComponent as EmptyStateImage } from "../../assets/emptyStateImage.svg";
 import { useTranslation } from "../../i18n";
-import { AGLocaleMap } from "../../locales/index";
+import {
+  createAgGridGetLocaleText,
+  getAgGridLocaleTextForLocale,
+  setAgGridLocaleText,
+  syncAgGridPaginationLocale,
+} from "../Table/agGridLocale";
 
 export const OldTable = forwardRef(
   (
@@ -119,6 +124,23 @@ export const OldTable = forwardRef(
     );
 
     const { t, locale } = useTranslation();
+    const localeTextRef = useRef(getAgGridLocaleTextForLocale(locale));
+    const getLocaleText = useMemo(
+      () => createAgGridGetLocaleText(localeTextRef),
+      []
+    );
+    const syncPaginationLocale = useCallback(() => {
+      syncAgGridPaginationLocale(
+        document.getElementById(gridId || "myGrid"),
+        localeTextRef.current
+      );
+    }, [gridId]);
+
+    useEffect(() => {
+      setAgGridLocaleText(localeTextRef, locale);
+      const frameId = requestAnimationFrame(syncPaginationLocale);
+      return () => cancelAnimationFrame(frameId);
+    }, [locale, syncPaginationLocale]);
 
     const getSaveViewCustomFilter = saveViewCustomFilter ?? {
       options: [
@@ -319,12 +341,14 @@ export const OldTable = forwardRef(
     }, [columnDefs]);
 
     const paginationChanged = (params) => {
+      syncPaginationLocale();
       setDynmaicStyleToButtonComponent();
       onPaginationChanged(params);
     };
 
     const onFirstDataRendered = (params) => {
       if (params?.api) params.api.getModel().appliedFontSize = tableFontSize;
+      syncPaginationLocale();
       args?.onFirstDataRendered?.(params);
       args?.gridOptions?.onFirstDataRendered?.(params);
     };
@@ -620,9 +644,8 @@ export const OldTable = forwardRef(
             }`}
           >
             <AgGridReact
-              {...args}
+              {...(({ localeText, getLocaleText, ...rest }) => rest)(args)}
               ref={actualRef}
-              key={`aggrid-${locale}`}
               suppressRowTransform={
                 viewPoint === "list" ? false : args?.suppressRowTransform
               }
@@ -651,7 +674,7 @@ export const OldTable = forwardRef(
               onFirstDataRendered={onFirstDataRendered}
               getRowHeight={getRowHeightWrapper}
               getRowClass={getRowClassWrapper}
-              localeText={AGLocaleMap?.[locale]}
+              getLocaleText={getLocaleText}
             />
           </div>
           {(bottomLeftOptions || bottomCenterOptions || args.pagination) && (

package/src/stories/I18n.mdx

@@ -0,0 +1,319 @@
+import { Meta } from "@storybook/blocks";
+import { LocaleDictionaryCollapse } from "./LocaleDictionaryCollapse";
+
+<Meta title="Internationalization" />
+
+<div className="ia-styles ia-guide-container i18n-guide">
+
+# Internationalization (i18n)
+
+`impact-ui` ships a built-in multi-language system based on React Context. Library components read their internal strings (labels, placeholders, messages, aria text, etc.) through it. Consuming apps can supply their own dictionaries, override library strings, and switch languages at runtime.
+
+**Shipped locales:** `en-US` (complete base) and `de-DE` (German).
+
+---
+
+## How it works
+
+Messages are resolved with a 3-layer merge (later layers win):
+
+1. **`en-US`** — guaranteed-complete base (nothing renders blank)
+2. **`ourDictionaries[locale]`** — impact-ui translation for the active locale (e.g. `de-DE`)
+3. **Host messages** — from your app’s `loadMessages(locale)` (always win)
+
+Interpolation uses `{placeholder}` tokens:
+
+```jsx
+t("monthPicker.placeholder", { format: "MM/YYYY" })
+// → "Select MM/YYYY" (en-US) / "Auswählen MM/YYYY" (de-DE)
+```
+
+Missing keys fall back to the key string itself so nothing renders blank.
+
+---
+
+## 1. Wrap your app with `I18nProvider`
+
+```jsx
+import { I18nProvider } from "impact-ui";
+
+const appMessages = {
+  "en-US": { "app.title": "My App" },
+  "de-DE": { "app.title": "Meine App" },
+};
+
+const App = () => (
+  <I18nProvider
+    defaultLocale="en-US"
+    loadMessages={(locale) => appMessages[locale] || {}}
+  >
+    <YourApp />
+  </I18nProvider>
+);
+```
+
+`loadMessages` can also return a Promise for lazy-loaded dictionaries:
+
+```jsx
+loadMessages={(locale) =>
+  import(`./locales/${locale}.json`).then((m) => m.default)
+}
+```
+
+> `I18nProvider` is optional — without it, components fall back to static English and `setLocale` becomes a no-op.
+
+---
+
+## 2. Translate your own strings with `useTranslation`
+
+Use this for any text your app passes into `impact-ui` components as props (titles, menu labels, etc.). Prefix your own keys (e.g. `app.*`) to avoid clashing with library keys (`common.*`, `table.*`, …):
+
+```jsx
+import { useTranslation, Header } from "impact-ui";
+
+const Example = () => {
+  const { t } = useTranslation();
+  return <Header title={t("app.header.title")} />;
+};
+```
+
+Library components (`Loader`, `Table`, `Sidebar`, `ChatBot`, `Select`, date pickers, etc.) translate their own internal strings automatically once `I18nProvider` is mounted — no extra props needed.
+
+---
+
+## 3. Switch the active language
+
+```jsx
+import { useI18n } from "impact-ui";
+
+const LanguageToggle = () => {
+  const { locale, setLocale } = useI18n();
+  return (
+    <button onClick={() => setLocale(locale === "en-US" ? "de-DE" : "en-US")}>
+      {locale}
+    </button>
+  );
+};
+```
+
+Or use the `Header` built-in language switcher:
+
+```jsx
+import { Header, useI18n } from "impact-ui";
+
+const AppHeader = () => {
+  const { setLocale } = useI18n();
+  return (
+    <Header
+      showLanguageIcon={true}
+    />
+  );
+};
+```
+
+Date pickers also sync `moment.locale`, and AG Grid uses the matching locale pack via `AGLocaleMap`.
+
+---
+
+## 4. Override library strings
+
+Return overrides from `loadMessages` using the same keys shipped by the library — host messages always win:
+
+```jsx
+loadMessages={(locale) => ({
+  "header.askIris":
+    locale === "de-DE" ? "Frag Iris" : "Ask Iris (custom)",
+})}
+```
+
+Inspect shipped keys in code:
+
+```js
+import { enUS, ourDictionaries } from "impact-ui";
+
+console.log(Object.keys(enUS));
+console.log(ourDictionaries["de-DE"]);
+```
+
+---
+
+## 5. Add a locale not shipped by the library
+
+`impact-ui` currently maintains `en-US` and `de-DE`. For any other locale, supply your own JSON via `loadMessages`. Library keys you don’t override fall back to English.
+
+```jsx
+const frFR = {
+  "common.cancel": "Annuler",
+  "common.apply": "Appliquer",
+  // …override only the keys you need
+};
+
+<I18nProvider
+  defaultLocale="fr-FR"
+  loadMessages={(locale) => (locale === "fr-FR" ? frFR : {})}
+>
+  <YourApp />
+</I18nProvider>
+```
+
+---
+
+## Storybook tooling
+
+Use the Storybook toolbar while browsing component stories:
+
+- **Language** — switch between English and Deutsch
+- **i18n Keys** — show raw keys (`common.cancel`) instead of translated text, so you can trace which key backs any visible string
+
+For consumer-style demos, stories can declare their own dictionary via `parameters.i18nMessages` and the `I18nDemo` helper (see any `Internationalized` story).
+
+---
+
+## Available exports
+
+| Export | Purpose |
+| --- | --- |
+| `I18nProvider` | Context provider — wrap your app |
+| `useTranslation` | `{ t, locale, … }` for translating strings |
+| `useI18n` | Full context (`locale`, `setLocale`, `messages`, `loading`, `t`) |
+| `I18nContext` | Raw React context (advanced) |
+| `buildMessages` / `translate` | Pure helpers (no React) |
+| `ourDictionaries` | Map of shipped locale → dictionary |
+| `enUS` | English base dictionary |
+| `BASE_LOCALE` | `"en-US"` |
+| `LOCALE_REGISTRY` | Labels + flag icons for the Header switcher |
+
+---
+
+## Shipped dictionaries
+
+Expand a panel below to inspect the live JSON used by the library. Content is imported from `src/locales/` so it stays in sync with the source files.
+
+<LocaleDictionaryCollapse />
+
+</div>
+
+<style>
+{`
+  .i18n-guide h1,
+  .i18n-guide h2,
+  .i18n-guide h3 {
+    margin-bottom: 12px;
+  }
+
+  .i18n-guide section,
+  .i18n-guide p {
+    margin-bottom: 12px;
+  }
+
+  .i18n-guide pre {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    border-radius: 6px;
+    padding: 12px 16px;
+    overflow-x: auto;
+    font-size: 13px;
+    line-height: 1.45;
+  }
+
+  .i18n-guide table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 12px 0 24px;
+    font-size: 14px;
+  }
+
+  .i18n-guide th,
+  .i18n-guide td {
+    border: 1px solid #e1e4e8;
+    padding: 8px 12px;
+    text-align: left;
+  }
+
+  .i18n-guide th {
+    background: #f6f8fa;
+  }
+
+  .i18n-dict-collapse {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    margin: 16px 0 32px;
+  }
+
+  .i18n-dict-panel {
+    border: 1px solid #d0d7de;
+    border-radius: 8px;
+    background: #fff;
+    overflow: hidden;
+  }
+
+  .i18n-dict-summary {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    padding: 12px 16px;
+    cursor: pointer;
+    list-style: none;
+    font-weight: 600;
+    font-size: 14px;
+    background: #f6f8fa;
+    user-select: none;
+  }
+
+  .i18n-dict-summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .i18n-dict-summary::before {
+    content: "▸";
+    display: inline-block;
+    margin-right: 8px;
+    transition: transform 0.15s ease;
+    color: #57606a;
+  }
+
+  .i18n-dict-panel[open] > .i18n-dict-summary::before {
+    transform: rotate(90deg);
+  }
+
+  .i18n-dict-summary-title {
+    flex: 1;
+  }
+
+  .i18n-dict-summary-meta {
+    font-weight: 500;
+    font-size: 12px;
+    color: #57606a;
+    background: #eaeef2;
+    border-radius: 999px;
+    padding: 2px 10px;
+  }
+
+  .i18n-dict-description {
+    margin: 12px 16px 0;
+    font-size: 13px;
+    color: #57606a;
+  }
+
+  .i18n-dict-pre {
+    margin: 12px 16px 16px;
+    max-height: 420px;
+    overflow: auto;
+    background: #0d1117;
+    color: #e6edf3;
+    border: none;
+    border-radius: 6px;
+    padding: 12px 16px;
+    font-size: 12px;
+    line-height: 1.5;
+  }
+
+  .i18n-dict-pre code {
+    background: transparent;
+    color: inherit;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  }
+`}
+</style>

package/src/stories/LocaleDictionaryCollapse.jsx

@@ -0,0 +1,44 @@
+import React from "react"; // dont remove
+import enUS from "../locales/en-US.json";
+import deDE from "../locales/de-DE.json";
+
+const dictionaries = [
+  {
+    code: "en-US",
+    title: "en-US.json — English (US)",
+    description: "Complete base dictionary. Missing keys in other locales fall back here.",
+    data: enUS,
+  },
+  {
+    code: "de-DE",
+    title: "de-DE.json — Deutsch",
+    description: "German translations shipped by impact-ui. Partial keys fall back to en-US.",
+    data: deDE,
+  },
+];
+
+/**
+ * Collapsible viewer for the shipped locale JSON files.
+ * Used by I18n.mdx so the full dictionaries don't dominate the docs page.
+ */
+export function LocaleDictionaryCollapse() {
+  return (
+    <div className="i18n-dict-collapse">
+      {dictionaries.map(({ code, title, description, data }) => {
+        const keyCount = Object.keys(data).length;
+        return (
+          <details key={code} className="i18n-dict-panel">
+            <summary className="i18n-dict-summary">
+              <span className="i18n-dict-summary-title">{title}</span>
+              <span className="i18n-dict-summary-meta">{keyCount} keys</span>
+            </summary>
+            <p className="i18n-dict-description">{description}</p>
+            <pre className="i18n-dict-pre">
+              <code style={{color:'black'}}>{JSON.stringify(data, null, 2)}</code>
+            </pre>
+          </details>
+        );
+      })}
+    </div>
+  );
+}

package/src/stories/storybookLinks.mdx

@@ -6,6 +6,7 @@ import { Meta } from "@storybook/blocks";
 
 ## Core Documentation
 - [Getting Started](https://impact-ui-v3.iaproducts.ai/?path=/docs/getting-started--docs)
+- [Internationalization](https://impact-ui-v3.iaproducts.ai/?path=/docs/internationalization--docs)
 - [Change Log](https://impact-ui-v3.iaproducts.ai/?path=/docs/change-log--docs)
 
 ## Patterns