@vendure/dashboard 3.5.0-minor-202509261210 → 3.5.0-minor-202510031341

package/src/lib/hooks/use-display-locale.ts

@@ -0,0 +1,40 @@
+import { useUserSettings } from './use-user-settings.js';
+
+const rtlLanguageCodes = ['ar', 'he', 'fa', 'ur', 'ps'];
+
+/**
+ * @description
+ * Returns information about the current display language & region.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   bcp47Tag,
+ *   humanReadableLanguageAndLocale,
+ *   humanReadableLanguage,
+ *   isRTL,
+ * } = useDisplayLocale();
+ *
+ * console.log(bcp47Tag) // "en-GB"
+ * console.log(humanReadableLanguage) // "English"
+ * console.log(humanReadableLanguageAndLocale) // "British English"
+ * console.log(isRTL) // false
+ * ```
+ *
+ * @docsCategory hooks
+ * @docsPage useDisplayLocale
+ */
+export function useDisplayLocale() {
+    const { settings } = useUserSettings();
+    const language = settings.displayLanguage.replace(/[_-]/, '-');
+    const locale = settings.displayLocale;
+    const bcp47Tag = language.match(/[_-]/)
+        ? language.replace(/[_-]/, '-')
+        : [language, locale].filter(x => !!x).join('-');
+    const humanReadableLanguageAndLocale = new Intl.DisplayNames([bcp47Tag], { type: 'language' }).of(
+        bcp47Tag,
+    );
+    const isRTL = rtlLanguageCodes.includes(language);
+    const humanReadableLanguage = new Intl.DisplayNames([bcp47Tag], { type: 'language' }).of(language);
+    return { bcp47Tag, humanReadableLanguageAndLocale, humanReadableLanguage, isRTL };
+}

package/src/lib/hooks/use-dynamic-translations.ts

@@ -0,0 +1,46 @@
+import { camelCaseToTitleCase } from '@/vdb/lib/utils.js';
+import { useLingui } from '@lingui/react';
+
+export function useDynamicTranslations() {
+    const { i18n } = useLingui();
+
+    const getTranslatedFieldName = (fieldId: string) => {
+        const fieldNameTranslationId = `fieldName.${fieldId}`;
+        const translatedDisplay = i18n.t(fieldNameTranslationId);
+        return translatedDisplay !== fieldNameTranslationId
+            ? translatedDisplay
+            : camelCaseToTitleCase(fieldId);
+    };
+
+    const getTranslatedOrderState = (state: string) => {
+        const stateTranslationId = `orderState.${state}`;
+        const translatedDisplay = i18n.t(stateTranslationId);
+        return translatedDisplay !== stateTranslationId ? translatedDisplay : camelCaseToTitleCase(state);
+    };
+
+    const getTranslatedFulfillmentState = (state: string) => {
+        const stateTranslationId = `fulfillmentState.${state}`;
+        const translatedDisplay = i18n.t(stateTranslationId);
+        return translatedDisplay !== stateTranslationId ? translatedDisplay : camelCaseToTitleCase(state);
+    };
+
+    const getTranslatedPaymentState = (state: string) => {
+        const stateTranslationId = `paymentState.${state}`;
+        const translatedDisplay = i18n.t(stateTranslationId);
+        return translatedDisplay !== stateTranslationId ? translatedDisplay : camelCaseToTitleCase(state);
+    };
+
+    const getTranslatedRefundState = (state: string) => {
+        const stateTranslationId = `refundState.${state}`;
+        const translatedDisplay = i18n.t(stateTranslationId);
+        return translatedDisplay !== stateTranslationId ? translatedDisplay : camelCaseToTitleCase(state);
+    };
+
+    return {
+        getTranslatedFieldName,
+        getTranslatedOrderState,
+        getTranslatedFulfillmentState,
+        getTranslatedPaymentState,
+        getTranslatedRefundState,
+    };
+}

package/src/lib/hooks/use-extended-detail-query.ts

@@ -1,5 +1,5 @@
 import { extendDetailFormQuery } from '@/vdb/framework/document-extension/extend-detail-form-query.js';
-import { useLingui } from '@/vdb/lib/trans.js';
+import { useLingui } from '@lingui/react/macro';
 import { DocumentNode } from 'graphql';
 import { useEffect, useMemo, useRef } from 'react';
 import { toast } from 'sonner';

package/src/lib/hooks/use-extended-list-query.ts

@@ -1,6 +1,6 @@
 import { getListQueryDocuments } from '@/vdb/framework/data-table/data-table-extensions.js';
 import { extendDocument } from '@/vdb/framework/document-extension/extend-document.js';
-import { useLingui } from '@/vdb/lib/trans.js';
+import { useLingui } from '@lingui/react/macro';
 import { DocumentNode } from 'graphql';
 import { useEffect, useMemo, useRef } from 'react';
 import { toast } from 'sonner';

package/src/lib/hooks/use-local-format.ts

@@ -1,5 +1,6 @@
 import { useCallback, useMemo } from 'react';
 
+import { useDisplayLocale } from './use-display-locale.js';
 import { useServerConfig } from './use-server-config.js';
 
 /**
@@ -26,7 +27,8 @@ import { useServerConfig } from './use-server-config.js';
 export function useLocalFormat() {
     const { moneyStrategyPrecision } = useServerConfig() ?? { moneyStrategyPrecision: 2 };
     const precisionFactor = useMemo(() => Math.pow(10, moneyStrategyPrecision), [moneyStrategyPrecision]);
-    const locale = 'en';
+    const { bcp47Tag } = useDisplayLocale();
+    const locale = bcp47Tag;
 
     const toMajorUnits = useCallback(
         (value: number): number => {
@@ -119,6 +121,17 @@ export function useLocalFormat() {
         [locale],
     );
 
+    const formatRegionName = useCallback(
+        (value: string): string => {
+            try {
+                return new Intl.DisplayNames([locale], { type: 'region' }).of(value) ?? value;
+            } catch (e: any) {
+                return value;
+            }
+        },
+        [locale],
+    );
+
     const formatCurrencyName = useCallback(
         (currencyCode: string, display: 'full' | 'symbol' | 'name' = 'full'): string => {
             if (!currencyCode) return '';
@@ -154,6 +167,7 @@ export function useLocalFormat() {
         formatDate,
         formatRelativeDate,
         formatLanguageName,
+        formatRegionName,
         formatCurrencyName,
         toMajorUnits,
         toMinorUnits,

package/src/lib/hooks/use-saved-views.ts

@@ -3,6 +3,7 @@ import {
     getSettingsStoreValueDocument,
     setSettingsStoreValueDocument,
 } from '@/vdb/graphql/settings-store-operations.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
 import { SavedView, SavedViewsStore, SaveViewInput, UpdateViewInput } from '@/vdb/types/saved-views.js';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { ColumnFiltersState } from '@tanstack/react-table';
@@ -19,6 +20,7 @@ const generateId = () => {
 
 export function useSavedViews() {
     const queryClient = useQueryClient();
+    const { settingsStoreIsAvailable } = useUserSettings();
     const { pageId } = usePage();
     const pageBlock = usePageBlock({ optional: true });
     const blockId = pageBlock?.blockId || 'default';
@@ -38,6 +40,8 @@ export function useSavedViews() {
             const allUserViews = (result?.getSettingsStoreValue as SavedViewsStore) || {};
             return allUserViews[pageId]?.[blockId] || [];
         },
+        retry: false,
+        enabled: settingsStoreIsAvailable,
     });
 
     // Query for global views
@@ -48,6 +52,8 @@ export function useSavedViews() {
             const allGlobalViews = (result?.getSettingsStoreValue as SavedViewsStore) || {};
             return allGlobalViews[pageId]?.[blockId] || [];
         },
+        retry: false,
+        enabled: settingsStoreIsAvailable,
     });
 
     // Save user view mutation
@@ -217,6 +223,7 @@ export function useSavedViews() {
     const canManageGlobalViews = hasPermissions(['WriteDashboardGlobalViews']);
 
     return {
+        savedViewsAreAvailable: settingsStoreIsAvailable,
         userViews: userViewsData || [],
         globalViews: globalViewsData || [],
         isLoading: userViewsLoading || globalViewsLoading,

package/src/lib/hooks/use-ui-language-loader.ts

@@ -0,0 +1,30 @@
+import { loadI18nMessages } from '@/vdb/lib/load-i18n-messages.js';
+import { useLingui } from '@lingui/react/macro';
+
+let currentlyLoading: string | null = null;
+
+/**
+ * @description
+ * Loads the UI translations for the given locale and activates it
+ * with the Lingui I18nProvider. Generally this is used internally
+ * when the display language is set via the user > language dialog.
+ *
+ * @docsCategory hooks
+ * @docsPage useUiLanguageLoader
+ */
+export function useUiLanguageLoader() {
+    const { i18n } = useLingui();
+
+    async function loadAndActivateLocale(locale: string) {
+        if (currentlyLoading === locale) {
+            return;
+        }
+        currentlyLoading = locale;
+        const messages = await loadI18nMessages(locale);
+        i18n.load(locale, messages);
+        i18n.activate(locale);
+        currentlyLoading = null;
+    }
+
+    return { loadAndActivateLocale };
+}

package/src/lib/lib/load-i18n-messages.ts

@@ -0,0 +1,17 @@
+import { Messages } from '@lingui/core';
+
+export async function loadI18nMessages(locale: string): Promise<Messages> {
+    if (import.meta.env.PROD) {
+        // We add the vite-ignore directive because we do not want to transform and
+        // bundle this dynamic import. Instead, we actually want to load it at runtime
+        // as a normal dynamic JS import.
+        // These i18n JS files are generated during build by the `translationsPlugin` in the
+        // vite-plugin-translations.ts file.
+        const { messages } = await import(/* @vite-ignore */ `./i18n/${locale}.js`);
+        return messages;
+    } else {
+        // In dev mode we allow the dynamic import behaviour
+        const { messages } = await import(`../../i18n/locales/${locale}.po`);
+        return messages;
+    }
+}

package/src/lib/lib/trans.tsx

@@ -1,16 +1,20 @@
+// export { Trans } from '@lingui/react/macro';
+// export { useLingui } from '@lingui/react';
+
+
 /**
  * This is a temporary work-around because the Lingui macros do not
  * currently work when the dashboard is packaged in an npm
  * module. Related issue: https://github.com/kentcdodds/babel-plugin-macros/issues/87
  */
-export function Trans({ children }: Readonly<{ children: React.ReactNode; context?: string }>) {
-    return <>{children}</>;
-}
-
-export function useLingui() {
-    return {
-        i18n: {
-            t: (key: string) => key,
-        },
-    };
-}
+// export function Trans({ children }: Readonly<{ children: React.ReactNode; context?: string }>) {
+//     return <>{children}</>;
+// }
+//
+// export function useLingui() {
+//     return {
+//         i18n: {
+//             t: (key: string) => key,
+//         },
+//     };
+// }

package/src/lib/providers/auth.tsx

@@ -1,3 +1,4 @@
+import { LS_KEY_SELECTED_CHANNEL_TOKEN } from '@/vdb/constants.js';
 import { api } from '@/vdb/graphql/api.js';
 import { graphql, ResultOf } from '@/vdb/graphql/graphql.js';
 import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
@@ -170,8 +171,7 @@ export function AuthProvider({ children }: Readonly<{ children: React.ReactNode
                     // Clear all cached queries to prevent stale data
                     queryClient.clear();
                     // Clear selected channel from localStorage
-                    localStorage.removeItem('vendure-selected-channel');
-                    localStorage.removeItem('vendure-selected-channel-token');
+                    localStorage.removeItem(LS_KEY_SELECTED_CHANNEL_TOKEN);
                     setStatus('unauthenticated');
                     setIsLoginLogoutInProgress(false);
                     onLogoutSuccess?.();

package/src/lib/providers/channel-provider.tsx

@@ -1,4 +1,5 @@
-import { api, SELECTED_CHANNEL_TOKEN_KEY } from '@/vdb/graphql/api.js';
+import { LS_KEY_SELECTED_CHANNEL_TOKEN } from '@/vdb/constants.js';
+import { api } from '@/vdb/graphql/api.js';
 import { graphql, ResultOf } from '@/vdb/graphql/graphql.js';
 import { useAuth } from '@/vdb/hooks/use-auth.js';
 import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
@@ -94,7 +95,7 @@ export interface ChannelContext {
  */
 function setChannelTokenInLocalStorage(channelToken: string) {
     try {
-        localStorage.setItem(SELECTED_CHANNEL_TOKEN_KEY, channelToken);
+        localStorage.setItem(LS_KEY_SELECTED_CHANNEL_TOKEN, channelToken);
     } catch (e) {
         console.error('Failed to store selected channel in localStorage', e);
     }

package/src/lib/providers/i18n-provider.tsx

@@ -1,11 +1,8 @@
+import { loadI18nMessages } from '@/vdb/lib/load-i18n-messages.js';
+import { i18n } from '@lingui/core';
+import { I18nProvider as LinguiI18nProvider } from '@lingui/react';
 import React from 'react';
-// import { i18n } from '@lingui/core';
-// import { I18nProvider as LinguiI18nProvider } from '@lingui/react';
 
-export const locales = {
-    en: 'English',
-    de: 'Deutsch',
-};
 export const defaultLocale = 'en';
 
 /**
@@ -13,16 +10,12 @@ export const defaultLocale = 'en';
  * @param locale any locale string
  */
 export async function dynamicActivate(locale: string, onActivate?: () => void) {
-    // Temporarily disabled because Lingui macros do not work when the dashboard is packaged in an npm module.
-    // Related issue: https://github.com/kentcdodds/babel-plugin-macros/issues/87
-
-    // const { messages } = await import(`../../i18n/locales/${locale}.po`);
-    // i18n.load(locale, messages);
-    // i18n.activate(locale);
+    const messages = await loadI18nMessages(locale);
+    i18n.load(locale, messages);
+    i18n.activate(locale);
     onActivate?.();
 }
 
 export function I18nProvider({ children }: { children: React.ReactNode }) {
-    // return <LinguiI18nProvider i18n={i18n}>{children}</LinguiI18nProvider>;
-    return <>{children}</>;
+    return <LinguiI18nProvider i18n={i18n}>{children}</LinguiI18nProvider>;
 }

package/src/lib/providers/user-settings.tsx

@@ -1,3 +1,4 @@
+import { LS_KEY_USER_SETTINGS } from '@/vdb/constants.js';
 import { QueryClient, useMutation, useQuery } from '@tanstack/react-query';
 import { ColumnFiltersState } from '@tanstack/react-table';
 import React, { createContext, useEffect, useRef, useState } from 'react';
@@ -43,6 +44,12 @@ const defaultSettings: UserSettings = {
 };
 
 export interface UserSettingsContextType {
+    /**
+     * @description
+     * Whether the server-side SettingsStore is available to use
+     * (i.e. the Vendure instance has the DashboardPlugin configured)
+     */
+    settingsStoreIsAvailable: boolean;
     settings: UserSettings;
     setDisplayLanguage: (language: string) => void;
     setDisplayLocale: (locale: string | undefined) => void;
@@ -63,7 +70,6 @@ export interface UserSettingsContextType {
 
 export const UserSettingsContext = createContext<UserSettingsContextType | undefined>(undefined);
 
-const STORAGE_KEY = 'vendure-user-settings';
 const SETTINGS_STORE_KEY = 'vendure.dashboard.userSettings';
 
 interface UserSettingsProviderProps {
@@ -75,7 +81,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     // Load settings from localStorage or use defaults
     const loadSettings = (): UserSettings => {
         try {
-            const storedSettings = localStorage.getItem(STORAGE_KEY);
+            const storedSettings = localStorage.getItem(LS_KEY_USER_SETTINGS);
             if (storedSettings) {
                 return { ...defaultSettings, ...JSON.parse(storedSettings) };
             }
@@ -86,19 +92,35 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     };
 
     const [settings, setSettings] = useState<UserSettings>(loadSettings);
+    const [settingsStoreIsAvailable, setSettingsStoreIsAvailable] = useState<boolean>(true);
     const [serverSettings, setServerSettings] = useState<UserSettings | null>(null);
     const [isReady, setIsReady] = useState(false);
     const previousContentLanguage = useRef(settings.contentLanguage);
     const saveInProgressRef = useRef(false);
 
     // Load settings from server on mount
-    const { data: serverSettingsResponse, isSuccess: serverSettingsLoaded } = useQuery({
+    const {
+        data: serverSettingsResponse,
+        isSuccess: serverSettingsLoaded,
+        error,
+    } = useQuery({
         queryKey: ['user-settings', SETTINGS_STORE_KEY],
         queryFn: () => api.query(getSettingsStoreValueDocument, { key: SETTINGS_STORE_KEY }),
         retry: false,
         staleTime: 0,
+        enabled: settingsStoreIsAvailable,
     });
 
+    useEffect(() => {
+        if (
+            settingsStoreIsAvailable &&
+            error?.message.includes('Settings store field not registered: vendure.dashboard.userSettings')
+        ) {
+            logSettingsStoreWarning();
+            setSettingsStoreIsAvailable(false);
+        }
+    }, [settingsStoreIsAvailable, error]);
+
     // Mutation to save settings to server
     const saveToServerMutation = useMutation({
         mutationFn: (settingsToSave: UserSettings) =>
@@ -144,7 +166,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     // Save settings to localStorage whenever they change
     useEffect(() => {
         try {
-            localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+            localStorage.setItem(LS_KEY_USER_SETTINGS, JSON.stringify(settings));
         } catch (e) {
             console.error('Failed to save user settings to localStorage', e);
         }
@@ -152,7 +174,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
 
     // Save to server when settings differ from server state
     useEffect(() => {
-        if (isReady && serverSettings && !saveInProgressRef.current) {
+        if (settingsStoreIsAvailable && isReady && serverSettings && !saveInProgressRef.current) {
             const serverDiffers = JSON.stringify(serverSettings) !== JSON.stringify(settings);
 
             if (serverDiffers) {
@@ -177,6 +199,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     };
 
     const contextValue: UserSettingsContextType = {
+        settingsStoreIsAvailable,
         settings,
         setDisplayLanguage: language => updateSetting('displayLanguage', language),
         setDisplayLocale: locale => updateSetting('displayLocale', locale),
@@ -201,3 +224,21 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
 
     return <UserSettingsContext.Provider value={contextValue}>{children}</UserSettingsContext.Provider>;
 };
+
+function logSettingsStoreWarning() {
+    // eslint-disable-next-line no-console
+    console.warn(
+        [
+            `User settings could not be fetched from the Vendure server.`,
+            `This suggests that the DashboardPlugin is not configured.`,
+            `Check your VendureConfig and ensure the DashboardPlugin is in your plugins array.`,
+            ``,
+            `By setting up the DashboardPlugin, you can take advantage of:`,
+            ` - Persisted settings across browsers and devices`,
+            ` - Saved views on list pages`,
+            ` - Metrics on the Insights page`,
+            ``,
+            `https://docs.vendure.io/reference/core-plugins/dashboard-plugin/`,
+        ].join('\n'),
+    );
+}