@vertesia/ui 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/src/features/views/viewState.test.ts

@@ -6,12 +6,13 @@ describe('View URL state', () => {
     it('parses repeated key terms and navigation values', () => {
         expect(
             parseViewState(
-                '?q=find+contracts&t.party=Acme&t.party=Globex&n.brand=Vertesia&display=cards&sort=updated&offset=20',
+                '?q=find+contracts&t.party=Acme&t.party=Globex&n.brand=Vertesia&nq.collections=legal&display=cards&sort=updated&offset=20',
             ),
         ).toEqual({
             query: 'find contracts',
             key_terms: { party: ['Acme', 'Globex'] },
             navigation: { brand: ['Vertesia'] },
+            navigation_queries: { collections: 'legal' },
             display: 'cards',
             sort: 'updated',
             offset: 20,
@@ -29,6 +30,7 @@ describe('View URL state', () => {
                     brand: ['Contoso', 'Vertesia'],
                     geography: [hierarchyPath],
                 },
+                navigation_queries: { collections: '  legal contracts  ' },
                 display: 'table',
             },
             '?account=account-1&project=project-1&q=stale&n.brand=stale',
@@ -44,6 +46,7 @@ describe('View URL state', () => {
                 geography: [hierarchyPath],
                 location: ['/Customers/Acme'],
             },
+            navigation_queries: { collections: 'legal contracts' },
             display: 'table',
         });
     });
@@ -59,6 +62,7 @@ describe('View URL state', () => {
                     query: '  contracts  ',
                     key_terms: { party: ['Acme'], retired: ['old'] },
                     navigation: { brand: ['stale'], retired: ['old'] },
+                    navigation_queries: { collections: 'legal', retired: 'old' },
                     display: 'retired',
                     sort: 'retired',
                     offset: 20,
@@ -77,6 +81,7 @@ describe('View URL state', () => {
                     total: 0,
                     navigation: {
                         brand: { id: 'brand', selected: ['Acme'], nodes: [] },
+                        collections: { id: 'collections', selected: [], nodes: [], query: 'legal' },
                     },
                     took: 5,
                 },
@@ -85,6 +90,7 @@ describe('View URL state', () => {
             query: 'contracts',
             key_terms: { party: ['Acme'] },
             navigation: { brand: ['Acme'] },
+            navigation_queries: { collections: 'legal' },
             display: 'table',
             sort: 'updated',
             offset: 20,

package/src/features/views/viewState.ts

@@ -6,6 +6,7 @@ const SORT_PARAM = 'sort';
 const OFFSET_PARAM = 'offset';
 const KEY_TERM_PREFIX = 't.';
 const NAVIGATION_PREFIX = 'n.';
+const NAVIGATION_QUERY_PREFIX = 'nq.';
 
 function nonNegativeInteger(value: string | null): number | undefined {
     if (value === null || value.trim() === '') return undefined;
@@ -23,6 +24,16 @@ function collectPrefixedValues(params: URLSearchParams, prefix: string): Record<
     return Object.keys(values).length > 0 ? values : undefined;
 }
 
+function collectPrefixedStrings(params: URLSearchParams, prefix: string): Record<string, string> | undefined {
+    const values: Record<string, string> = {};
+    for (const key of new Set(params.keys())) {
+        if (!key.startsWith(prefix) || key.length === prefix.length) continue;
+        const value = params.get(key)?.trim();
+        if (value) values[key.slice(prefix.length)] = value;
+    }
+    return Object.keys(values).length > 0 ? values : undefined;
+}
+
 /** Parse the stable, shareable URL representation of a View execution request. */
 export function parseViewState(search: string): ExecuteViewRequest {
     const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
@@ -32,11 +43,13 @@ export function parseViewState(search: string): ExecuteViewRequest {
     const offset = nonNegativeInteger(params.get(OFFSET_PARAM));
     const key_terms = collectPrefixedValues(params, KEY_TERM_PREFIX);
     const navigation = collectPrefixedValues(params, NAVIGATION_PREFIX);
+    const navigation_queries = collectPrefixedStrings(params, NAVIGATION_QUERY_PREFIX);
 
     return {
         ...(query ? { query } : {}),
         ...(key_terms ? { key_terms } : {}),
         ...(navigation ? { navigation } : {}),
+        ...(navigation_queries ? { navigation_queries } : {}),
         ...(display ? { display } : {}),
         ...(sort ? { sort } : {}),
         ...(offset ? { offset } : {}),
@@ -51,6 +64,7 @@ function deleteManagedParams(params: URLSearchParams): void {
             key === SORT_PARAM ||
             key === OFFSET_PARAM ||
             key.startsWith(KEY_TERM_PREFIX) ||
+            key.startsWith(NAVIGATION_QUERY_PREFIX) ||
             key.startsWith(NAVIGATION_PREFIX)
         ) {
             params.delete(key);
@@ -67,6 +81,13 @@ function appendRecord(params: URLSearchParams, prefix: string, values: Record<st
     }
 }
 
+function appendStringRecord(params: URLSearchParams, prefix: string, values: Record<string, string> | undefined): void {
+    if (!values) return;
+    for (const [key, value] of Object.entries(values).sort(([left], [right]) => left.localeCompare(right))) {
+        if (value.trim()) params.set(`${prefix}${key}`, value.trim());
+    }
+}
+
 /** Serialize View state while preserving unrelated host parameters such as account/project selection. */
 export function serializeViewState(request: ExecuteViewRequest, currentSearch = ''): string {
     const params = new URLSearchParams(currentSearch.startsWith('?') ? currentSearch.slice(1) : currentSearch);
@@ -78,6 +99,7 @@ export function serializeViewState(request: ExecuteViewRequest, currentSearch =
     if (request.offset && request.offset > 0) params.set(OFFSET_PARAM, String(request.offset));
     appendRecord(params, KEY_TERM_PREFIX, request.key_terms);
     appendRecord(params, NAVIGATION_PREFIX, request.navigation);
+    appendStringRecord(params, NAVIGATION_QUERY_PREFIX, request.navigation_queries);
 
     const value = params.toString();
     return value ? `?${value}` : '';
@@ -92,6 +114,14 @@ function selectedRecord(result: ViewExecutionResult): Record<string, string[]> |
     return Object.keys(selections).length > 0 ? selections : undefined;
 }
 
+function navigationQueryRecord(result: ViewExecutionResult): Record<string, string> | undefined {
+    const queries: Record<string, string> = {};
+    for (const [id, navigation] of Object.entries(result.navigation)) {
+        if (navigation.query) queries[id] = navigation.query;
+    }
+    return Object.keys(queries).length > 0 ? queries : undefined;
+}
+
 /** Remove stale configuration IDs and apply the display/sort selected by the authoritative runtime. */
 export function canonicalizeViewState(request: ExecuteViewRequest, result: ViewExecutionResult): ExecuteViewRequest {
     const keyTermIds = new Set(result.definition.search?.key_terms?.map((term) => term.id) ?? []);
@@ -101,11 +131,13 @@ export function canonicalizeViewState(request: ExecuteViewRequest, result: ViewE
           )
         : undefined;
     const navigation = selectedRecord(result);
+    const navigation_queries = navigationQueryRecord(result);
 
     return {
         ...(request.query?.trim() ? { query: request.query.trim() } : {}),
         ...(key_terms && Object.keys(key_terms).length > 0 ? { key_terms } : {}),
         ...(navigation ? { navigation } : {}),
+        ...(navigation_queries ? { navigation_queries } : {}),
         ...(result.display ? { display: result.display } : {}),
         ...(result.sort ? { sort: result.sort } : {}),
         ...(request.offset && request.offset > 0 ? { offset: request.offset } : {}),

package/src/i18n/LanguageProvider.tsx

@@ -1,5 +1,5 @@
 import { DirectionProvider } from '@radix-ui/react-direction';
-import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
 import { isRTL, resolveLanguage, type SupportedLanguage } from './rtl.js';
 
 type LanguageProviderProps = {
@@ -10,7 +10,7 @@ type LanguageProviderProps = {
 
 type LanguageProviderState = {
     language: SupportedLanguage;
-    setLanguage: (language: SupportedLanguage) => void;
+    setLanguage: (language: SupportedLanguage, options?: { persist?: boolean }) => void;
     isRTL: boolean;
 };
 
@@ -39,7 +39,9 @@ export function LanguageProvider({
     storageKey = 'vertesia-ui-language',
     ...props
 }: LanguageProviderProps) {
-    const [language, setLanguage] = useState<SupportedLanguage>(() => readInitialLanguage(storageKey, defaultLanguage));
+    const [language, setLanguageState] = useState<SupportedLanguage>(() =>
+        readInitialLanguage(storageKey, defaultLanguage),
+    );
 
     const rtl = isRTL(language);
 
@@ -49,16 +51,21 @@ export function LanguageProvider({
         root.dir = rtl ? 'rtl' : 'ltr';
     }, [language, rtl]);
 
+    const setLanguage = useCallback(
+        (next: SupportedLanguage, options?: { persist?: boolean }) => {
+            if (options?.persist !== false) window.localStorage?.setItem(storageKey, next);
+            setLanguageState(next);
+        },
+        [storageKey],
+    );
+
     const value = useMemo<LanguageProviderState>(
         () => ({
             language,
             isRTL: rtl,
-            setLanguage: (next: SupportedLanguage) => {
-                window.localStorage?.setItem(storageKey, next);
-                setLanguage(next);
-            },
+            setLanguage,
         }),
-        [language, rtl, storageKey],
+        [language, rtl, setLanguage],
     );
 
     return (

package/src/i18n/instance.test.ts

@@ -0,0 +1,30 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { i18nInstance } from './instance.js';
+
+const KEY = 'abac_perms.collection.content_manager';
+
+describe('i18n instance', () => {
+    afterAll(async () => {
+        await i18nInstance.changeLanguage('en');
+    });
+
+    it('serves the bundled English fallback', async () => {
+        await i18nInstance.changeLanguage('en');
+        expect(i18nInstance.t(KEY)).toBe('Collection Manager');
+    });
+
+    it('loads a locale that is not bundled', async () => {
+        await i18nInstance.changeLanguage('fr');
+        expect(i18nInstance.t(KEY)).toBe('Gestionnaire de collection');
+    });
+
+    it('keeps a region-tagged locale distinct from its base language', async () => {
+        await i18nInstance.changeLanguage('zh-TW');
+        expect(i18nInstance.t(KEY)).not.toBe('Collection Manager');
+    });
+
+    it('falls back to English for an unsupported language', async () => {
+        await i18nInstance.changeLanguage('nl');
+        expect(i18nInstance.t(KEY)).toBe('Collection Manager');
+    });
+});

package/src/i18n/instance.ts

@@ -1,50 +1,77 @@
-import i18next, { type i18n } from 'i18next';
+import i18next, { type BackendModule, type i18n, type ReadCallback } from 'i18next';
 import { initReactI18next } from 'react-i18next';
-import ar from './locales/ar.json';
-import de from './locales/de.json';
 import en from './locales/en.json';
-import es from './locales/es.json';
-import fr from './locales/fr.json';
-import it from './locales/it.json';
-import ja from './locales/ja.json';
-import ko from './locales/ko.json';
-import pt from './locales/pt.json';
-import ru from './locales/ru.json';
-import tr from './locales/tr.json';
-import zh from './locales/zh.json';
-import zhTW from './locales/zh-TW.json';
 
 export const NAMESPACE = 'vertesia.ui';
 
-// Scoped instance — does NOT touch the global i18next singleton
-const i18nInstance: i18n = i18next.createInstance();
+type LocaleLoader = () => Promise<{ default: Record<string, unknown> }>;
 
-void i18nInstance.use(initReactI18next).init({
-    resources: {
-        ar: { [NAMESPACE]: ar },
-        de: { [NAMESPACE]: de },
-        en: { [NAMESPACE]: en },
-        es: { [NAMESPACE]: es },
-        fr: { [NAMESPACE]: fr },
-        it: { [NAMESPACE]: it },
-        ja: { [NAMESPACE]: ja },
-        ko: { [NAMESPACE]: ko },
-        pt: { [NAMESPACE]: pt },
-        ru: { [NAMESPACE]: ru },
-        tr: { [NAMESPACE]: tr },
-        zh: { [NAMESPACE]: zh },
-        'zh-TW': { [NAMESPACE]: zhTW },
-    },
-    fallbackLng: 'en',
-    returnEmptyString: false,
-    ns: [NAMESPACE],
-    defaultNS: NAMESPACE,
-    interpolation: {
-        escapeValue: false, // React already escapes
+/**
+ * Every locale except the `en` fallback is fetched the first time it is selected. Bundling all
+ * thirteen costs ~1 MB of JSON, of which a given user reads at most one — and the fallback covers
+ * the gap while a translation is in flight.
+ */
+const LOCALE_LOADERS: Record<string, LocaleLoader> = {
+    ar: () => import('./locales/ar.json'),
+    de: () => import('./locales/de.json'),
+    es: () => import('./locales/es.json'),
+    fr: () => import('./locales/fr.json'),
+    it: () => import('./locales/it.json'),
+    ja: () => import('./locales/ja.json'),
+    ko: () => import('./locales/ko.json'),
+    pt: () => import('./locales/pt.json'),
+    ru: () => import('./locales/ru.json'),
+    tr: () => import('./locales/tr.json'),
+    zh: () => import('./locales/zh.json'),
+    'zh-TW': () => import('./locales/zh-TW.json'),
+};
+
+/** Every locale this instance can serve: the bundled `en` fallback plus the lazily loaded ones. */
+export const AVAILABLE_LOCALES: readonly string[] = ['en', ...Object.keys(LOCALE_LOADERS)];
+
+const lazyLocaleBackend: BackendModule = {
+    type: 'backend',
+    init: () => {
+        // no configuration: the locale set is fixed at build time
     },
-    react: {
-        useSuspense: false, // Translations are bundled, no async loading
+    read(language: string, _namespace: string, callback: ReadCallback) {
+        const load = LOCALE_LOADERS[language];
+        if (!load) {
+            // Unsupported language: report an empty bundle so i18next falls back to `en`
+            callback(null, {});
+            return;
+        }
+        load().then(
+            (locale) => callback(null, locale.default),
+            (err: unknown) => callback(err instanceof Error ? err : new Error(String(err)), false),
+        );
     },
-});
+};
+
+// Scoped instance — does NOT touch the global i18next singleton
+const i18nInstance: i18n = i18next.createInstance();
+
+void i18nInstance
+    .use(lazyLocaleBackend)
+    .use(initReactI18next)
+    .init({
+        // `en` stays bundled so the fallback — and the common case — needs no round trip
+        resources: {
+            en: { [NAMESPACE]: en },
+        },
+        // Required to consult the backend even though `resources` are supplied
+        partialBundledLanguages: true,
+        fallbackLng: 'en',
+        returnEmptyString: false,
+        ns: [NAMESPACE],
+        defaultNS: NAMESPACE,
+        interpolation: {
+            escapeValue: false, // React already escapes
+        },
+        react: {
+            // Render the `en` fallback while a locale loads rather than suspending the tree
+            useSuspense: false,
+        },
+    });
 
 export { i18nInstance };