@maxal_studio/kratosjs-react 1.0.0

package/src/hooks/useAfterStateUpdated.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef } from 'react';
+import { useWatch, useFormContext } from 'react-hook-form';
+import { executeSerializedFunction } from '../runtime/serializedFunctions';
+
+/**
+ * Hook to execute afterStateUpdated callback when a field's value changes
+ * @param fieldName - Name of the field to watch
+ * @param callbackString - Serialized callback function as string
+ */
+export function useAfterStateUpdated(fieldName: string, callbackString?: string) {
+	const { control, getValues, setValue } = useFormContext();
+	const currentValue = useWatch({ control, name: fieldName });
+	const previousValueRef = useRef<any>(currentValue);
+
+	useEffect(() => {
+		// Skip if no callback is provided
+		if (!callbackString) return;
+
+		// Skip on initial mount (when previousValue is undefined)
+		if (previousValueRef.current === undefined && currentValue === undefined) {
+			return;
+		}
+
+		// Check if value actually changed
+		const hasChanged = previousValueRef.current !== currentValue;
+
+		if (hasChanged) {
+			try {
+				// Create get function to access form values
+				const get = (field: string) => {
+					// Support dot notation for nested fields
+					const keys = field.split('.');
+					let value = getValues();
+
+					for (const key of keys) {
+						if (value === undefined || value === null) {
+							return undefined;
+						}
+						value = value[key];
+					}
+
+					return value;
+				};
+
+				// Create set function to update form values
+				const set = (field: string, value: any) => {
+					setValue(field, value, {
+						shouldValidate: true,
+						shouldDirty: true,
+						shouldTouch: true,
+					});
+				};
+
+				// Evaluate the callback function using the shared utility
+				// The function should be in the format: (get, set, state, old) => { ... }
+				// Reconstruct the function first, then call it with the parameters
+				const callback = executeSerializedFunction(callbackString);
+				if (typeof callback === 'function') {
+					// Call it with the required parameters
+					callback(get, set, currentValue, previousValueRef.current);
+				}
+			} catch (error) {
+				console.error('Error executing afterStateUpdated callback:', error);
+			}
+		}
+
+		// Update previous value for next comparison
+		previousValueRef.current = currentValue;
+	}, [currentValue, callbackString, getValues, setValue]);
+}

package/src/hooks/useValidation.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { useValidation } from './useValidation';
+
+// The hook no longer re-implements rule semantics: it delegates to the shared
+// ValidationEngine via a single RHF `validate` function. These tests confirm
+// the wiring (required → native RHF, everything else → engine) and that the
+// verdicts match the engine the backend also uses.
+
+function wrapper({ children }: { children: React.ReactNode }) {
+	function Inner() {
+		const methods = useForm();
+		return React.createElement(FormProvider, methods as any, children);
+	}
+	return React.createElement(Inner);
+}
+
+function runValidate(result: ReturnType<typeof useValidation>, value: any, formValues: Record<string, any> = {}) {
+	return result.validate?.kratos(value, formValues);
+}
+
+describe('useValidation', () => {
+	it('maps required to RHF native (drives the asterisk)', () => {
+		const { result } = renderHook(() => useValidation(['required'], 'create', 'name'), { wrapper });
+		expect(result.current.required).toBe('This field is required');
+	});
+
+	it('delegates email validation to the engine', () => {
+		const { result } = renderHook(() => useValidation(['email'], 'create', 'email'), { wrapper });
+		expect(runValidate(result.current, 'a@b.com')).toBe(true);
+		expect(runValidate(result.current, 'nope')).toMatch(/valid email/);
+	});
+
+	it('delegates min length to the engine', () => {
+		const { result } = renderHook(() => useValidation(['min:3'], 'create', 'title'), { wrapper });
+		expect(runValidate(result.current, 'abc')).toBe(true);
+		expect(runValidate(result.current, 'ab')).toMatch(/at least 3 characters/);
+	});
+
+	it('enforces alpha (parity with the backend)', () => {
+		const { result } = renderHook(() => useValidation(['alpha'], 'create', 'code'), { wrapper });
+		expect(runValidate(result.current, 'abc')).toBe(true);
+		expect(runValidate(result.current, 'ab1')).toMatch(/letters/);
+	});
+
+	it('resolves cross-field rules against form values', () => {
+		const { result } = renderHook(() => useValidation(['same:password'], 'create', 'confirm'), { wrapper });
+		expect(runValidate(result.current, 'x', { password: 'x' })).toBe(true);
+		expect(runValidate(result.current, 'x', { password: 'y' })).toMatch(/must match password/);
+	});
+
+	it('skips rules whose condition is false', () => {
+		const rules = [{ rule: 'required', condition: false }];
+		const { result } = renderHook(() => useValidation(rules, 'create', 'name'), { wrapper });
+		expect(result.current.required).toBeUndefined();
+	});
+});

package/src/hooks/useValidation.ts

@@ -0,0 +1,95 @@
+import { useMemo } from 'react';
+import { useWatch, useFormContext } from 'react-hook-form';
+import { RHFValidationRules } from '../types';
+import type { ValidationRule } from '@maxal_studio/kratosjs';
+// Runtime engine is imported from the pure /dist/validation subpath (no server
+// code), so it never drags Panel/MikroORM/Express into the browser bundle.
+import { ValidationEngine } from '@maxal_studio/kratosjs/dist/validation';
+import { evaluateCondition } from '../runtime/conditions';
+import { useI18nContext } from '../i18n/I18nProvider';
+
+/**
+ * Validation rule with optional condition
+ */
+interface ValidationRuleWithCondition {
+	rule: ValidationRule;
+	condition?: boolean | string; // Serialized function string or boolean
+}
+
+/**
+ * Hook to convert KratosJs validation rules to React Hook Form format.
+ *
+ * Rule semantics are NOT re-implemented here: after resolving each rule's
+ * condition against the live form state, the surviving rules are handed to the
+ * shared `ValidationEngine` — the SAME engine the backend runs — via a single
+ * RHF `validate` function. This guarantees the client and server agree on every
+ * rule and message. `required` is additionally mapped to RHF's native
+ * `required` so the required-asterisk UI keeps working.
+ *
+ * @param rules Validation rules (strings, or objects with rule + condition)
+ * @param operation Current operation ('create' | 'edit' | 'view')
+ * @param fieldName Name of the field being validated (for cross-field rules and messages)
+ * @returns React Hook Form validation object
+ */
+export function useValidation(
+	rules: (ValidationRule | ValidationRuleWithCondition)[] = [],
+	operation?: 'create' | 'edit' | 'view',
+	fieldName = '',
+): RHFValidationRules {
+	const { control } = useFormContext();
+	const formState = useWatch({ control }) || {};
+	const { t } = useI18nContext();
+
+	return useMemo(() => {
+		const validation: RHFValidationRules = {};
+
+		// Resolve conditions against the live form state, keeping only the
+		// rule strings that currently apply.
+		const activeRules: string[] = [];
+		rules.forEach(ruleOrObj => {
+			let rule: ValidationRule;
+			let condition: boolean | string | undefined;
+
+			if (typeof ruleOrObj === 'object' && ruleOrObj !== null && 'rule' in ruleOrObj) {
+				rule = ruleOrObj.rule;
+				condition = ruleOrObj.condition;
+			} else {
+				rule = ruleOrObj as ValidationRule;
+			}
+
+			if (condition !== undefined) {
+				const shouldApply = evaluateCondition(condition, formState, operation);
+				if (!shouldApply) return;
+			}
+
+			if (typeof rule === 'string') activeRules.push(rule);
+		});
+
+		// `required` → RHF native (drives the asterisk + empty-value enforcement).
+		if (activeRules.includes('required')) {
+			validation.required = t('core:validation.required_generic');
+		}
+
+		// Everything else is delegated to the shared engine. `required` is handled
+		// natively above, so it's excluded here to avoid a duplicate message.
+		const engineRules = activeRules.filter(r => r !== 'required');
+		if (engineRules.length > 0) {
+			validation.validate = {
+				...((validation.validate as any) || {}),
+				kratos: (value: any, formValues: any) => {
+					const violations = ValidationEngine.validateValue(value, engineRules, {
+						allValues: formValues || {},
+						field: fieldName,
+					});
+					if (violations.length === 0) return true;
+					const v = violations[0];
+					// Render in the active locale when the rule provides an i18n key;
+					// otherwise use the already-rendered message (overrides/inline).
+					return v.messageKey ? t(`core:${v.messageKey}`, v.params) : v.message;
+				},
+			};
+		}
+
+		return validation;
+	}, [rules, formState, operation, fieldName, t]);
+}

package/src/i18n/I18nProvider.tsx

@@ -0,0 +1,128 @@
+import React, { createContext, useContext, useEffect, useMemo, useState, useCallback } from 'react';
+import type { KratosI18n } from '@maxal_studio/kratosjs/dist/i18n';
+import { buildClientI18n, type ClientI18nConfig } from './buildClientI18n';
+import { setActiveI18n } from './activeLocale';
+
+const STORAGE_KEY = 'kratosjs-locale';
+
+export interface I18nContextValue {
+	/** The underlying engine (escape hatch). */
+	engine: KratosI18n;
+	/** Active UI locale. */
+	locale: string;
+	/** Switch the active locale (persists + updates `<html lang/dir>` + re-fetches). */
+	setLocale: (locale: string) => void;
+	/** Supported locales. */
+	locales: string[];
+	/** Text direction of the active locale. */
+	dir: 'ltr' | 'rtl';
+	/** Translate a (possibly `ns:`-prefixed) key against the active locale. */
+	t: (key: string, params?: Record<string, unknown>) => string;
+}
+
+const I18nContext = createContext<I18nContextValue | null>(null);
+
+// Lazy default engine so components used outside a provider (isolated tests, the
+// pre-mount window) still resolve `core` chrome instead of crashing.
+let defaultEngine: KratosI18n | null = null;
+function getDefaultEngine(): KratosI18n {
+	if (!defaultEngine) defaultEngine = buildClientI18n();
+	return defaultEngine;
+}
+
+function resolveInitialLocale(engine: KratosI18n, configDefault?: string): string {
+	const locales = engine.getLocales();
+	const stored = typeof localStorage !== 'undefined' ? localStorage.getItem(STORAGE_KEY) : null;
+	if (stored && locales.includes(stored)) return stored;
+	if (configDefault && locales.includes(configDefault)) return configDefault;
+	const nav = typeof navigator !== 'undefined' ? navigator.language : '';
+	if (nav) {
+		if (locales.includes(nav)) return nav;
+		const base = nav.split('-')[0];
+		if (locales.includes(base)) return base;
+	}
+	return engine.getDefaultLocale();
+}
+
+export interface I18nProviderProps {
+	config?: ClientI18nConfig;
+	children: React.ReactNode;
+}
+
+export function I18nProvider({ config, children }: I18nProviderProps) {
+	const engine = useMemo(() => buildClientI18n(config), [config]);
+	const [locale, setLocaleState] = useState(() => resolveInitialLocale(engine, config?.defaultLocale));
+
+	// Set the module mirror SYNCHRONOUSLY during render (not only in the effect) so
+	// non-hook `translate()` calls in children resolve the correct locale on the
+	// very first paint — important for a persisted non-default locale.
+	useMemo(() => setActiveI18n(engine, locale), [engine, locale]);
+
+	// Keep the <html> attributes + storage in sync with the locale.
+	useEffect(() => {
+		setActiveI18n(engine, locale);
+		if (typeof document !== 'undefined') {
+			document.documentElement.lang = locale;
+			document.documentElement.dir = engine.getDir(locale);
+		}
+		if (typeof localStorage !== 'undefined') localStorage.setItem(STORAGE_KEY, locale);
+	}, [engine, locale]);
+
+	const setLocale = useCallback(
+		(next: string) => {
+			if (next === locale) return;
+			// Persist + apply the document attributes immediately, then do a full
+			// refresh so EVERY view — metadata, already-open table/form schemas, and
+			// server-rendered labels — re-fetches and re-renders in the new locale.
+			// (Schemas are cached per-mount, so a targeted re-fetch would miss them.)
+			if (typeof localStorage !== 'undefined') localStorage.setItem(STORAGE_KEY, next);
+			if (typeof document !== 'undefined') {
+				document.documentElement.lang = next;
+				document.documentElement.dir = engine.getDir(next);
+			}
+			try {
+				if (typeof window !== 'undefined' && typeof window.location?.reload === 'function') {
+					window.location.reload();
+					return;
+				}
+			} catch {
+				// jsdom/SSR: reload isn't implemented — fall through to in-place update.
+			}
+			setLocaleState(next);
+		},
+		[locale, engine],
+	);
+
+	const value = useMemo<I18nContextValue>(
+		() => ({
+			engine,
+			locale,
+			setLocale,
+			locales: engine.getLocales(),
+			dir: engine.getDir(locale),
+			t: (key, params) => engine.t(key, { locale, ...params }),
+		}),
+		[engine, locale, setLocale],
+	);
+
+	return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+}
+
+/**
+ * Read the i18n context. Degrades gracefully to a default `core`-only engine when
+ * no `<I18nProvider>` is mounted (so isolated component tests don't all need wrapping).
+ */
+export function useI18nContext(): I18nContextValue {
+	const ctx = useContext(I18nContext);
+	if (ctx) return ctx;
+	const engine = getDefaultEngine();
+	const locale = engine.getDefaultLocale();
+	return {
+		engine,
+		locale,
+		setLocale: () => {},
+		locales: engine.getLocales(),
+		dir: engine.getDir(locale),
+		t: (key, params) => engine.t(key, { locale, ...params }),
+	};
+}

package/src/i18n/LocaleSwitcher.tsx

@@ -0,0 +1,50 @@
+import { useI18nContext } from './I18nProvider';
+
+/** Human label for a locale code, in the locale's own language (falls back to the code). */
+function localeLabel(code: string): string {
+	try {
+		const dn = new Intl.DisplayNames([code], { type: 'language' });
+		const name = dn.of(code);
+		if (name) return name.charAt(0).toUpperCase() + name.slice(1);
+	} catch {
+		// Intl.DisplayNames unavailable — fall through.
+	}
+	return code;
+}
+
+export interface LocaleSwitcherProps {
+	className?: string;
+	/** Accessible label (defaults to the translated `core:panel.language`). */
+	'aria-label'?: string;
+}
+
+/**
+ * Native `<select>` locale switcher. Renders nothing when the panel has a single
+ * locale. Used in the Header account menu and on the login screen.
+ */
+export function LocaleSwitcher({ className, ...rest }: LocaleSwitcherProps) {
+	const { locale, setLocale, locales, t } = useI18nContext();
+	if (locales.length <= 1) return null;
+
+	return (
+		<select
+			value={locale}
+			onChange={e => setLocale(e.target.value)}
+			aria-label={rest['aria-label'] ?? t('core:panel.language')}
+			className={
+				className ??
+				'k-input text-sm py-1.5 px-3 pr-8 rounded-md border border-border focus:outline-none focus:ring-2 focus:ring-ring focus:border-accent disabled:opacity-50 disabled:cursor-not-allowed transition-colors appearance-none bg-no-repeat bg-right'
+			}
+			style={{
+				backgroundImage: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3E%3Cpath stroke='%236b7280' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' d='M6 8l4 4 4-4'/%3E%3C/svg%3E")`,
+				backgroundPosition: 'right 0.5rem center',
+				backgroundSize: '1.5em 1.5em',
+			}}>
+			{locales.map(code => (
+				<option key={code} value={code}>
+					{localeLabel(code)}
+				</option>
+			))}
+		</select>
+	);
+}

package/src/i18n/activeLocale.ts

@@ -0,0 +1,39 @@
+// Module-level mirror of the active client locale + engine.
+//
+// Lets non-hook utilities (formatValue, tableFormatters) localize via `translate`
+// / `getActiveLocale` without threading a locale argument through every call.
+// The I18nProvider keeps this in sync with React state on every locale change.
+
+import type { KratosI18n } from '@maxal_studio/kratosjs/dist/i18n';
+import { buildClientI18n } from './buildClientI18n';
+
+let activeEngine: KratosI18n | null = null;
+let activeLocale = 'en';
+let defaultEngine: KratosI18n | null = null;
+
+/** The active engine, or a lazily-built `core`-only default (no provider mounted). */
+function engine(): KratosI18n {
+	if (activeEngine) return activeEngine;
+	if (!defaultEngine) defaultEngine = buildClientI18n();
+	return defaultEngine;
+}
+
+/** Update the active engine + locale (called by I18nProvider). */
+export function setActiveI18n(next: KratosI18n, locale: string): void {
+	activeEngine = next;
+	activeLocale = locale;
+}
+
+/** The active locale, e.g. for `Intl` formatters. Defaults to `'en'`. */
+export function getActiveLocale(): string {
+	return activeLocale;
+}
+
+/**
+ * Translate `key` against the active locale. Falls back to a `core`-only default
+ * engine when no provider has mounted (so isolated tests + pre-mount utilities
+ * still resolve chrome). Prefer `useTranslation` inside components.
+ */
+export function translate(key: string, params?: Record<string, unknown>): string {
+	return engine().t(key, { locale: activeLocale, ...params });
+}

package/src/i18n/buildClientI18n.ts

@@ -0,0 +1,101 @@
+// Build the client KratosI18n from the server-injected config + optional overrides.
+//
+// The backend is the single source of truth: it injects the plugin + app catalogs
+// (and the locale config) into the admin HTML, and the client consumes them here.
+//
+// Catalog precedence (later wins): package chrome (`core`) → server-injected
+// resources (plugin + app namespaces) → optional mount-time overrides. App override
+// catalogs may target any namespace via a `ns:` key prefix (e.g. `core:common.save`
+// overrides a built-in chrome string); unprefixed keys go to the `app` namespace.
+
+import {
+	createI18n,
+	type KratosI18n,
+	type I18nResources,
+	type Catalog,
+	type Direction,
+} from '@maxal_studio/kratosjs/dist/i18n';
+import { clientCoreResources } from './locales/core';
+
+/** Per-locale catalog map, e.g. `{ en: {...}, sq: {...} }`. */
+export type ClientTranslations = Record<string, Catalog>;
+
+export interface ClientI18nConfig {
+	defaultLocale?: string;
+	fallbackLocale?: string;
+	locales?: string[];
+	/** Text direction per locale, forwarded from the server for app-added RTL locales. */
+	directions?: Record<string, Direction>;
+	/**
+	 * Server-injected catalogs (`namespace -> locale -> catalog`) for the plugin and
+	 * app namespaces. Populated from `window.__VALAJS_I18N__`.
+	 */
+	resources?: I18nResources;
+	/**
+	 * Optional mount-time override catalogs by locale. Keys may be `ns:key`
+	 * (defaults to the `app` namespace) — mainly to override built-in `core:` chrome.
+	 */
+	translations?: ClientTranslations;
+}
+
+function mergeInto(target: I18nResources, namespace: string, locale: string, catalog: Catalog): void {
+	const ns = (target[namespace] ??= {});
+	ns[locale] = { ...(ns[locale] ?? {}), ...catalog };
+}
+
+/**
+ * Assemble the `namespace -> locale -> catalog` resources for the client engine.
+ */
+export function buildClientResources(config: ClientI18nConfig = {}): I18nResources {
+	const resources: I18nResources = {};
+
+	// 1. Package chrome (core namespace) — bundled with the React package.
+	for (const [locale, catalog] of Object.entries(clientCoreResources)) {
+		mergeInto(resources, 'core', locale, catalog);
+	}
+
+	// 2. Server-injected catalogs (plugin + app namespaces, already in the right
+	//    app-wins precedence from the backend merge).
+	for (const [namespace, byLocale] of Object.entries(config.resources ?? {})) {
+		for (const [locale, catalog] of Object.entries(byLocale)) {
+			mergeInto(resources, namespace, locale, catalog);
+		}
+	}
+
+	// 3. Mount-time overrides (last → win). A `ns:` prefix routes the key to that
+	//    namespace, so the app can override core/plugin strings; otherwise `app`.
+	for (const [locale, catalog] of Object.entries(config.translations ?? {})) {
+		for (const [key, value] of Object.entries(catalog)) {
+			const idx = key.indexOf(':');
+			const namespace = idx === -1 ? 'app' : key.slice(0, idx);
+			const realKey = idx === -1 ? key : key.slice(idx + 1);
+			mergeInto(resources, namespace, locale, { [realKey]: value });
+		}
+	}
+
+	return resources;
+}
+
+/** Locales discovered across all registered catalogs (plus any declared). */
+export function discoverClientLocales(resources: I18nResources, declared?: string[]): string[] {
+	if (declared && declared.length > 0) return declared;
+	const set = new Set<string>();
+	for (const byLocale of Object.values(resources)) {
+		for (const locale of Object.keys(byLocale)) set.add(locale);
+	}
+	return set.size > 0 ? [...set] : ['en'];
+}
+
+/** Create the client engine from the server-injected config + optional overrides. */
+export function buildClientI18n(config: ClientI18nConfig = {}): KratosI18n {
+	const resources = buildClientResources(config);
+	const locales = discoverClientLocales(resources, config.locales);
+	const defaultLocale = config.defaultLocale ?? (locales.includes('en') ? 'en' : locales[0]);
+	return createI18n({
+		locales,
+		defaultLocale,
+		fallbackLocale: config.fallbackLocale ?? defaultLocale,
+		directions: config.directions,
+		resources,
+	});
+}

package/src/i18n/i18n.test.tsx

@@ -0,0 +1,140 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+import React from 'react';
+import { render, screen, renderHook, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { I18nProvider } from './I18nProvider';
+import { useTranslation } from './useTranslation';
+import { useLocale } from './useLocale';
+import { useFormatter } from './useFormatter';
+import { LocaleSwitcher } from './LocaleSwitcher';
+import { buildClientResources, buildClientI18n } from './buildClientI18n';
+
+const config = {
+	defaultLocale: 'en',
+	translations: {
+		en: { 'home.title': 'Home', 'core:common.save': 'Save it' },
+		sq: { 'home.title': 'Ballina', 'core:common.save': 'Ruaje' },
+	},
+};
+
+function wrapper({ children }: { children: React.ReactNode }) {
+	return <I18nProvider config={config}>{children}</I18nProvider>;
+}
+
+beforeEach(() => localStorage.clear());
+
+describe('buildClientResources', () => {
+	it('routes app keys: bare → app namespace, ns: prefix → that namespace', () => {
+		const res = buildClientResources(config);
+		expect(res.app.en['home.title']).toBe('Home');
+		// `core:common.save` overrides the package chrome default.
+		expect(res.core.en['common.save']).toBe('Save it');
+		// Built-in chrome still present for non-overridden keys.
+		expect(res.core.en['common.cancel']).toBe('Cancel');
+	});
+
+	it('merges server-injected resources (plugin + app namespaces)', () => {
+		const res = buildClientResources({
+			resources: {
+				twofa: { en: { title: 'Verify' } },
+				app: { en: { 'users.label': 'Users' } },
+			},
+		});
+		expect(res.twofa.en['title']).toBe('Verify');
+		expect(res.app.en['users.label']).toBe('Users');
+		// Built-in chrome is still present alongside injected catalogs.
+		expect(res.core.en['common.cancel']).toBe('Cancel');
+	});
+
+	it('lets mount-time translations override server-injected resources', () => {
+		const res = buildClientResources({
+			resources: { app: { en: { 'users.label': 'Users' } } },
+			translations: { en: { 'users.label': 'People' } },
+		});
+		expect(res.app.en['users.label']).toBe('People');
+	});
+
+	it('localizes built-in chrome for a custom locale via injected `core` resources', () => {
+		// Backend registered `core` chrome for French (a locale the package does not bundle)
+		// plus an English override — both arrive via the injected resources.
+		const res = buildClientResources({
+			locales: ['en', 'fr'],
+			resources: { core: { fr: { 'common.save': 'Enregistrer' }, en: { 'common.save': 'Store' } } },
+		});
+		// New locale gets chrome from the injected catalog.
+		expect(res.core.fr['common.save']).toBe('Enregistrer');
+		// Injected `core` overrides the bundled default for existing locales...
+		expect(res.core.en['common.save']).toBe('Store');
+		// ...while non-overridden bundled chrome keys stay intact.
+		expect(res.core.en['common.cancel']).toBe('Cancel');
+	});
+
+	it('resolves chrome in a custom locale end-to-end through the engine', () => {
+		const engine = buildClientI18n({
+			locales: ['en', 'fr'],
+			defaultLocale: 'en',
+			resources: { core: { fr: { 'common.save': 'Enregistrer' } } },
+		});
+		expect(engine.t('core:common.save', { locale: 'fr' })).toBe('Enregistrer');
+		expect(engine.getLocales()).toContain('fr');
+	});
+});
+
+describe('useTranslation', () => {
+	it('translates chrome + app keys (app overrides core)', () => {
+		const { result } = renderHook(() => useTranslation(), { wrapper });
+		expect(result.current.t('app:home.title')).toBe('Home');
+		expect(result.current.t('core:common.save')).toBe('Save it'); // app override
+		expect(result.current.t('core:common.cancel')).toBe('Cancel'); // package default
+	});
+
+	it('switching locale persists the choice and triggers a full refresh', () => {
+		const reload = vi.fn();
+		Object.defineProperty(window, 'location', { value: { reload }, writable: true });
+		const { result } = renderHook(() => useLocale(), { wrapper });
+		act(() => result.current.setLocale('sq'));
+		expect(localStorage.getItem('kratosjs-locale')).toBe('sq');
+		expect(document.documentElement.lang).toBe('sq');
+		expect(reload).toHaveBeenCalled();
+	});
+
+	it('falls back to a default engine outside any provider', () => {
+		const { result } = renderHook(() => useTranslation());
+		expect(result.current.t('core:common.save')).toBe('Save'); // built-in default
+	});
+});
+
+describe('LocaleSwitcher', () => {
+	it('renders the registered locales and switches on change', async () => {
+		const reload = vi.fn();
+		Object.defineProperty(window, 'location', { value: { reload }, writable: true });
+		render(
+			<I18nProvider config={config}>
+				<LocaleSwitcher />
+			</I18nProvider>,
+		);
+		const select = screen.getByRole('combobox');
+		expect(select).toBeInTheDocument();
+		await userEvent.selectOptions(select, 'sq');
+		expect(localStorage.getItem('kratosjs-locale')).toBe('sq');
+		expect(document.documentElement.lang).toBe('sq');
+		expect(reload).toHaveBeenCalled();
+	});
+
+	it('renders nothing for a single-locale panel', () => {
+		render(
+			<I18nProvider config={{ defaultLocale: 'en', locales: ['en'], translations: { en: {} } }}>
+				<LocaleSwitcher />
+			</I18nProvider>,
+		);
+		expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+	});
+});
+
+describe('useFormatter', () => {
+	it('formats currency and relative time in the active locale', () => {
+		const { result } = renderHook(() => useFormatter(), { wrapper });
+		expect(result.current.currency(1234.5, 'USD')).toContain('1,234.50');
+		expect(result.current.relativeTime(-2, 'hour')).toBe('2 hours ago');
+	});
+});