@molecule/app-react 1.0.0

package/dist/hooks/useStorage.js

@@ -0,0 +1,144 @@
+/**
+ * React hook for storage.
+ *
+ * @module
+ */
+import { useCallback, useContext, useEffect, useState } from 'react';
+import { t } from '@molecule/app-i18n';
+import { StorageContext } from '../contexts.js';
+/**
+ * Hook to access the storage provider from context.
+ *
+ * @returns The storage provider from context
+ * @throws {Error} Error if used outside of StorageProvider
+ */
+export function useStorageProvider() {
+    const provider = useContext(StorageContext);
+    if (!provider) {
+        throw new Error(t('react.error.useStorageOutsideProvider', undefined, {
+            defaultValue: 'useStorageProvider must be used within a StorageProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Hook to manage a single storage value with React state sync.
+ *
+ * @param key - Storage key
+ * @param options - Hook options
+ *
+ * @example
+ * ```tsx
+ * const { value: theme, setValue: setTheme, loading } = useStorageValue<string>('theme', {
+ *   defaultValue: 'light'
+ * })
+ *
+ * if (loading) return <Spinner />
+ * return (
+ *   <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+ *     <option value="light">Light</option>
+ *     <option value="dark">Dark</option>
+ *   </select>
+ * )
+ * ```
+ * @returns Storage value state (value, loading, error) and mutators (setValue, removeValue).
+ */
+export function useStorageValue(key, options) {
+    const storage = useStorageProvider();
+    const { defaultValue, sync = false } = options ?? {};
+    const [value, setValueState] = useState(defaultValue);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Load initial value
+    useEffect(() => {
+        let mounted = true;
+        const loadValue = async () => {
+            try {
+                const stored = await storage.get(key);
+                if (mounted) {
+                    setValueState(stored ?? defaultValue);
+                    setLoading(false);
+                }
+            }
+            catch (err) {
+                if (mounted) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                    setLoading(false);
+                }
+            }
+        };
+        loadValue();
+        return () => {
+            mounted = false;
+        };
+    }, [key, storage, defaultValue]);
+    // Sync across tabs if supported
+    useEffect(() => {
+        if (!sync)
+            return;
+        const handleStorageChange = (event) => {
+            if (event.key === key && event.newValue !== null) {
+                try {
+                    const newValue = JSON.parse(event.newValue);
+                    setValueState(newValue);
+                }
+                catch (_error) {
+                    // JSON.parse failed on newValue — the cross-tab sync is best-effort and the
+                    // local state already holds the last good value, so ignoring is safe here.
+                }
+            }
+        };
+        window.addEventListener('storage', handleStorageChange);
+        return () => window.removeEventListener('storage', handleStorageChange);
+    }, [key, sync]);
+    const setValue = useCallback(async (newValue) => {
+        try {
+            await storage.set(key, newValue);
+            setValueState(newValue);
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+    }, [key, storage]);
+    const removeValue = useCallback(async () => {
+        try {
+            await storage.remove(key);
+            setValueState(defaultValue);
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+    }, [key, storage, defaultValue]);
+    return {
+        value,
+        setValue,
+        removeValue,
+        loading,
+        error,
+    };
+}
+/**
+ * Hook for simple storage operations without React state sync.
+ *
+ * @returns Storage operation methods
+ */
+export function useStorage() {
+    const storage = useStorageProvider();
+    const get = useCallback((key) => storage.get(key), [storage]);
+    const set = useCallback((key, value) => storage.set(key, value), [storage]);
+    const remove = useCallback((key) => storage.remove(key), [storage]);
+    const clear = useCallback(() => storage.clear(), [storage]);
+    const keys = useCallback(() => storage.keys(), [storage]);
+    return {
+        get,
+        set,
+        remove,
+        clear,
+        keys,
+    };
+}
+//# sourceMappingURL=useStorage.js.map

package/dist/hooks/useStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorage.js","sourceRoot":"","sources":["../../src/hooks/useStorage.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useStore.d.ts

@@ -0,0 +1,51 @@
+/**
+ * React hook for state management.
+ *
+ * @module
+ */
+import type { StateProvider, Store } from '@molecule/app-state';
+import type { UseStoreOptions } from '../types.js';
+/**
+ * Hook to access the state provider from context.
+ *
+ * @returns The state provider from context
+ * @throws {Error} Error if used outside of StateProvider
+ */
+export declare function useStateProvider(): StateProvider;
+/**
+ * Hook to subscribe to a store with optional selector and equality function.
+ *
+ * @param store - The store to subscribe to
+ * @param options - Hook options (selector, equalityFn)
+ * @returns The selected state
+ *
+ * @example
+ * ```tsx
+ * const count = useStore(counterStore)
+ * const doubled = useStore(counterStore, { selector: (s) => s.count * 2 })
+ * ```
+ */
+export declare function useStore<T, S = T>(store: Store<T>, options?: UseStoreOptions<T, S>): S;
+/**
+ * Hook to get the store's setState function.
+ *
+ * @param store - The store to get setState from
+ * @returns The setState function
+ */
+export declare function useSetStore<T>(store: Store<T>): Store<T>['setState'];
+/**
+ * Hook to create a bound action for a store.
+ *
+ * @param store - The store to bind to
+ * @param action - The action function that receives setState and getState
+ * @returns A bound action function
+ *
+ * @example
+ * ```tsx
+ * const increment = useStoreAction(counterStore, (setState, getState) => () => {
+ *   setState({ count: getState().count + 1 })
+ * })
+ * ```
+ */
+export declare function useStoreAction<T, Args extends unknown[], R>(store: Store<T>, action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R): (...args: Args) => R;
+//# sourceMappingURL=useStore.d.ts.map

package/dist/hooks/useStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAUhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAgCtF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACzD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,MAAM,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAC/F,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,CAKtB"}

package/dist/hooks/useStore.js

@@ -0,0 +1,86 @@
+/**
+ * React hook for state management.
+ *
+ * @module
+ */
+import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
+import { t } from '@molecule/app-i18n';
+import { StateContext } from '../contexts.js';
+/**
+ * Hook to access the state provider from context.
+ *
+ * @returns The state provider from context
+ * @throws {Error} Error if used outside of StateProvider
+ */
+export function useStateProvider() {
+    const provider = useContext(StateContext);
+    if (!provider) {
+        throw new Error(t('react.error.useStoreOutsideProvider', undefined, {
+            defaultValue: 'useStateProvider must be used within a StateProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Hook to subscribe to a store with optional selector and equality function.
+ *
+ * @param store - The store to subscribe to
+ * @param options - Hook options (selector, equalityFn)
+ * @returns The selected state
+ *
+ * @example
+ * ```tsx
+ * const count = useStore(counterStore)
+ * const doubled = useStore(counterStore, { selector: (s) => s.count * 2 })
+ * ```
+ */
+export function useStore(store, options) {
+    // Validate that we're within a StateProvider
+    useStateProvider();
+    const { selector, equalityFn } = options ?? {};
+    // Use a ref to track the previous selected value for equality comparison
+    const prevSelectedRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const state = store.getState();
+        const selected = selector ? selector(state) : state;
+        // If we have an equality function and a previous value, check equality
+        if (equalityFn && prevSelectedRef.current !== undefined) {
+            if (equalityFn(prevSelectedRef.current, selected)) {
+                return prevSelectedRef.current;
+            }
+        }
+        prevSelectedRef.current = selected;
+        return selected;
+    }, [store, selector, equalityFn]);
+    const subscribe = useCallback((onStoreChange) => {
+        return store.subscribe(onStoreChange);
+    }, [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Hook to get the store's setState function.
+ *
+ * @param store - The store to get setState from
+ * @returns The setState function
+ */
+export function useSetStore(store) {
+    return store.setState;
+}
+/**
+ * Hook to create a bound action for a store.
+ *
+ * @param store - The store to bind to
+ * @param action - The action function that receives setState and getState
+ * @returns A bound action function
+ *
+ * @example
+ * ```tsx
+ * const increment = useStoreAction(counterStore, (setState, getState) => () => {
+ *   setState({ count: getState().count + 1 })
+ * })
+ * ```
+ */
+export function useStoreAction(store, action) {
+    return useCallback((...args) => action(store.setState, store.getState)(...args), [store, action]);
+}
+//# sourceMappingURL=useStore.js.map

package/dist/hooks/useStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE7E,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,qCAAqC,EAAE,SAAS,EAAE;YAClD,YAAY,EAAE,sDAAsD;SACrE,CAAC,CACH,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAW,KAAe,EAAE,OAA+B;IACjF,6CAA6C;IAC7C,gBAAgB,EAAE,CAAA;IAElB,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAE9C,yEAAyE;IACzE,MAAM,eAAe,GAAG,MAAM,CAAgB,SAAS,CAAC,CAAA;IAExD,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAsB,CAAA;QAErE,uEAAuE;QACvE,IAAI,UAAU,IAAI,eAAe,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACxD,IAAI,UAAU,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAClD,OAAO,eAAe,CAAC,OAAO,CAAA;YAChC,CAAC;QACH,CAAC;QAED,eAAe,CAAC,OAAO,GAAG,QAAQ,CAAA;QAClC,OAAO,QAAQ,CAAA;IACjB,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA;IAEjC,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE;QAC5B,OAAO,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,CAAA;IACvC,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAA;IAED,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,KAAe;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAA;AACvB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EACf,MAAgG;IAEhG,OAAO,WAAW,CAChB,CAAC,GAAG,IAAU,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,EAClE,CAAC,KAAK,EAAE,MAAM,CAAC,CAChB,CAAA;AACH,CAAC"}

package/dist/hooks/useTheme.d.ts

@@ -0,0 +1,50 @@
+/**
+ * React hook for theming.
+ *
+ * @module
+ */
+import type { Theme, ThemeProvider } from '@molecule/app-theme';
+import type { UseThemeResult } from '../types.js';
+/**
+ * Hook to access the theme provider from context.
+ *
+ * @returns The theme provider from context
+ * @throws {Error} Error if used outside of ThemeProvider
+ */
+export declare function useThemeProvider(): ThemeProvider;
+/**
+ * Hook for theme state and actions.
+ *
+ * @returns Theme state and actions
+ *
+ * @example
+ * ```tsx
+ * const { theme, themeName, setTheme, toggleTheme } = useTheme()
+ *
+ * return (
+ *   <button onClick={toggleTheme}>
+ *     Current theme: {themeName}
+ *   </button>
+ * )
+ * ```
+ */
+export declare function useTheme(): UseThemeResult;
+/**
+ * Hook to get just the current theme object.
+ *
+ * @returns The current theme
+ */
+export declare function useCurrentTheme(): Theme;
+/**
+ * Hook to get just the theme mode (light/dark).
+ *
+ * @returns The current theme mode
+ */
+export declare function useThemeMode(): 'light' | 'dark';
+/**
+ * Hook to get theme colors.
+ *
+ * @returns The current theme colors
+ */
+export declare function useThemeColors(): Theme['colors'];
+//# sourceMappingURL=useTheme.d.ts.map

package/dist/hooks/useTheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/hooks/useTheme.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAUhD;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CA4DzC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAGvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,GAAG,MAAM,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,KAAK,CAAC,QAAQ,CAAC,CAGhD"}

package/dist/hooks/useTheme.js

@@ -0,0 +1,135 @@
+/**
+ * React hook for theming.
+ *
+ * @module
+ */
+import { useCallback, useContext, useEffect, useState } from 'react';
+import { t } from '@molecule/app-i18n';
+import { ThemeContext } from '../contexts.js';
+/**
+ * Hook to access the theme provider from context.
+ *
+ * @returns The theme provider from context
+ * @throws {Error} Error if used outside of ThemeProvider
+ */
+export function useThemeProvider() {
+    const provider = useContext(ThemeContext);
+    if (!provider) {
+        throw new Error(t('react.error.useThemeOutsideProvider', undefined, {
+            defaultValue: 'useThemeProvider must be used within a ThemeProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Subscribe to a theme provider, supporting both `subscribe` and `onThemeChange` methods.
+ * @param provider - The ThemeProvider instance to subscribe to.
+ * @param callback - Listener invoked whenever the active theme changes.
+ * @returns An unsubscribe function that removes the listener.
+ */
+function subscribeToThemeProvider(provider, callback) {
+    if (typeof provider.subscribe === 'function') {
+        return provider.subscribe(callback);
+    }
+    if (typeof provider
+        .onThemeChange === 'function') {
+        return provider.onThemeChange(callback);
+    }
+    return () => { };
+}
+/**
+ * Hook for theme state and actions.
+ *
+ * @returns Theme state and actions
+ *
+ * @example
+ * ```tsx
+ * const { theme, themeName, setTheme, toggleTheme } = useTheme()
+ *
+ * return (
+ *   <button onClick={toggleTheme}>
+ *     Current theme: {themeName}
+ *   </button>
+ * )
+ * ```
+ */
+export function useTheme() {
+    const provider = useThemeProvider();
+    const [theme, setThemeState] = useState(() => provider.getTheme());
+    const [themeName, setThemeName] = useState(() => {
+        return typeof provider
+            .getThemeName === 'function'
+            ? provider.getThemeName()
+            : provider.getTheme().name;
+    });
+    useEffect(() => {
+        const unsubscribe = subscribeToThemeProvider(provider, () => {
+            setThemeState(provider.getTheme());
+            setThemeName(typeof provider
+                .getThemeName === 'function'
+                ? provider.getThemeName()
+                : provider.getTheme().name);
+        });
+        return unsubscribe;
+    }, [provider]);
+    // Memoized action wrappers
+    const setTheme = useCallback((name) => provider.setTheme(name), [provider]);
+    const toggleTheme = useCallback(() => {
+        // Prefer the provider's purpose-built light/dark toggle. `toggleMode`
+        // is a required `ThemeProvider` method and the semantically correct
+        // action for a light/dark toggle — unlike `getThemes()`, which is
+        // optional, so the index-cycle below silently no-ops for providers
+        // that don't implement it. The index-cycle is kept only as a fallback
+        // for non-conforming providers that predate `toggleMode`.
+        if (typeof provider.toggleMode === 'function') {
+            provider.toggleMode();
+            return;
+        }
+        const themes = provider.getThemes?.() ?? [];
+        if (themes.length === 0)
+            return;
+        const currentName = typeof provider
+            .getThemeName === 'function'
+            ? provider.getThemeName()
+            : provider.getTheme().name;
+        const currentIndex = themes.findIndex((t) => typeof t === 'string' ? t === currentName : t.name === currentName);
+        const nextIndex = (currentIndex + 1) % themes.length;
+        const next = themes[nextIndex];
+        provider.setTheme(typeof next === 'string' ? next : next.name);
+    }, [provider]);
+    return {
+        theme,
+        themeName,
+        setTheme,
+        toggleTheme,
+        mode: theme.mode,
+    };
+}
+/**
+ * Hook to get just the current theme object.
+ *
+ * @returns The current theme
+ */
+export function useCurrentTheme() {
+    const { theme } = useTheme();
+    return theme;
+}
+/**
+ * Hook to get just the theme mode (light/dark).
+ *
+ * @returns The current theme mode
+ */
+export function useThemeMode() {
+    const { mode } = useTheme();
+    return mode;
+}
+/**
+ * Hook to get theme colors.
+ *
+ * @returns The current theme colors
+ */
+export function useThemeColors() {
+    const { theme } = useTheme();
+    return theme.colors;
+}
+//# sourceMappingURL=useTheme.js.map

package/dist/hooks/useTheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTheme.js","sourceRoot":"","sources":["../../src/hooks/useTheme.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useTranslation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * React hook for internationalization.
+ *
+ * @module
+ */
+import type { I18nProvider } from '@molecule/app-i18n';
+import type { UseTranslationResult } from '../types.js';
+/**
+ * Hook to access the i18n provider from context.
+ *
+ * @returns The i18n provider from context
+ * @throws {Error} Error if used outside of I18nProvider
+ */
+export declare function useI18nProvider(): I18nProvider;
+/**
+ * Hook for internationalization.
+ *
+ * @returns Translation function and locale management
+ *
+ * @example
+ * ```tsx
+ * const { t, locale, setLocale, formatNumber } = useTranslation()
+ *
+ * return (
+ *   <div>
+ *     <h1>{t('welcome.title', { name: 'User' })}</h1>
+ *     <p>{formatNumber(1234.56, { style: 'currency', currency: 'USD' })}</p>
+ *     <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+ *       <option value="en">English</option>
+ *       <option value="es">Spanish</option>
+ *     </select>
+ *   </div>
+ * )
+ * ```
+ */
+export declare function useTranslation(): UseTranslationResult;
+/**
+ * Hook to get just the translation function.
+ *
+ * @returns The translation function
+ */
+export declare function useT(): I18nProvider['t'];
+/**
+ * Hook to get the current locale.
+ *
+ * @returns The current locale code
+ */
+export declare function useLocale(): string;
+/**
+ * Hook to get the text direction.
+ *
+ * @returns The text direction ('ltr' or 'rtl')
+ */
+export declare function useDirection(): 'ltr' | 'rtl';
+/**
+ * Translates an error at render time so the displayed message updates automatically
+ * when the locale changes.
+ *
+ * **Always use this hook to display errors in React components** — accessing
+ * `error.message` directly bypasses re-translation and leaves stale text after a
+ * locale switch. If `error` is an `I18nError` (thrown via `throw new I18nError(key)`),
+ * its key is translated using the current locale. For plain `Error` instances,
+ * `error.message` is returned unchanged.
+ *
+ * @param error - The error to translate, or `null`/`undefined`.
+ * @returns The translated error string, or `null` if no error.
+ */
+export declare function useI18nError(error: Error | null | undefined): string | null;
+//# sourceMappingURL=useTranslation.d.ts.map

package/dist/hooks/useTranslation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslation.d.ts","sourceRoot":"","sources":["../../src/hooks/useTranslation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAEV,YAAY,EAGb,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEvD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,CAqDrD;AAED;;;;GAIG;AACH,wBAAgB,IAAI,IAAI,YAAY,CAAC,GAAG,CAAC,CAUxC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,KAAK,GAAG,KAAK,CAG5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAW3E"}