@wilshop/dashboard 3.5.2

package/src/lib/graphql/graphql.ts

@@ -0,0 +1,15 @@
+import type { introspection } from './graphql-env.d.ts';
+import { initGraphQLTada } from 'gql.tada';
+
+export const graphql = initGraphQLTada<{
+    disableMasking: true;
+    introspection: introspection;
+    scalars: {
+        DateTime: string;
+        JSON: any;
+        Money: number;
+    };
+}>();
+
+export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
+export { readFragment } from 'gql.tada';

package/src/lib/graphql/settings-store-operations.ts

@@ -0,0 +1,17 @@
+import { graphql } from './graphql.js';
+
+export const getSettingsStoreValueDocument = graphql(`
+    query GetSettingsStoreValue($key: String!) {
+        getSettingsStoreValue(key: $key)
+    }
+`);
+
+export const setSettingsStoreValueDocument = graphql(`
+    mutation SetSettingsStoreValue($input: SettingsStoreInput!) {
+        setSettingsStoreValue(input: $input) {
+            key
+            result
+            error
+        }
+    }
+`);

package/src/lib/hooks/use-alerts.ts

@@ -0,0 +1,84 @@
+import { AlertSeverity, DashboardAlertDefinition } from '@/vdb/framework/extension-api/types/alerts.js';
+import { useAlertsContext } from '@/vdb/providers/alerts-provider.js';
+import { useMemo } from 'react';
+
+/**
+ * @description
+ * An individual Alert item.
+ *
+ * @docsCategory hooks
+ * @docsPage useAlerts
+ * @since 3.5.0
+ */
+export interface AlertEntry {
+    definition: DashboardAlertDefinition;
+    active: boolean;
+    currentSeverity?: AlertSeverity;
+    lastData: any;
+    dismiss: () => void;
+}
+
+/**
+ * @description
+ * Returns information about all registered Alerts, including how many are
+ * active and at what severity.
+ *
+ * @docsCategory hooks
+ * @docsPage useAlerts
+ * @docsWeight 0
+ * @since 3.5.0
+ */
+export function useAlerts(): { alerts: AlertEntry[]; activeCount: number; highestSeverity: AlertSeverity } {
+    const { alertDefs, rawResults, dismissedAlerts, setDismissedAlerts } = useAlertsContext();
+
+    const alerts = useMemo(() => {
+        return rawResults.map((result, idx) => {
+            const alertDef = alertDefs[idx];
+            const dismissedAt = dismissedAlerts.get(alertDef.id);
+            const isDismissed =
+                dismissedAt !== undefined &&
+                result.dataUpdatedAt !== undefined &&
+                dismissedAt > result.dataUpdatedAt;
+            const active = alertDef.shouldShow(result.data) && !isDismissed;
+            const currentSeverity = getSeverity(alertDef, result.data);
+            return {
+                definition: alertDef,
+                active,
+                lastData: result.data,
+                currentSeverity,
+                dismiss: () => {
+                    setDismissedAlerts(prev => new Map(prev).set(alertDef.id, Date.now()));
+                },
+            };
+        });
+    }, [rawResults, alertDefs, dismissedAlerts]);
+
+    const activeCount = useMemo(() => alerts.filter(alert => alert.active).length, [alerts]);
+    const highestSeverity: AlertSeverity =
+        alerts.length > 0
+            ? alerts.reduce((highest, a) => {
+                  if (highest === 'warning' && a.currentSeverity === 'error') {
+                      return 'error';
+                  }
+                  if (
+                      highest === 'info' &&
+                      (a.currentSeverity === 'warning' || a.currentSeverity === 'error')
+                  ) {
+                      return a.currentSeverity;
+                  }
+                  return highest;
+              }, 'info' as AlertSeverity)
+            : 'info';
+
+    return { alerts, activeCount, highestSeverity };
+}
+
+function getSeverity(alertDef: DashboardAlertDefinition, data: any) {
+    if (typeof alertDef.severity === 'string') {
+        return alertDef.severity;
+    } else if (typeof alertDef.severity === 'function') {
+        return alertDef.severity(data);
+    } else {
+        return 'info';
+    }
+}

package/src/lib/hooks/use-auth.tsx

@@ -0,0 +1,21 @@
+import { AuthContext } from '@/vdb/providers/auth.js';
+import * as React from 'react';
+
+/**
+ * @description
+ * Provides access to the {@link AuthContext} which contains information
+ * about the active channel.
+ *
+ *
+ * @docsCategory hooks
+ * @docsPage useAuth
+ * @docsWeight 0
+ * @since 3.3.0
+ */
+export function useAuth() {
+    const context = React.useContext(AuthContext);
+    if (!context) {
+        throw new Error('useAuth must be used within an AuthProvider');
+    }
+    return context;
+}

package/src/lib/hooks/use-channel.ts

@@ -0,0 +1,27 @@
+import { ChannelContext } from '@/vdb/providers/channel-provider.js';
+import * as React from 'react';
+
+// Hook to use the channel context
+
+/**
+ * @description
+ * Provides access to the {@link ChannelContext} which contains information
+ * about the active channel.
+ *
+ * @example
+ * ```tsx
+ * const { activeChannel } = useChannel();
+ * ```
+ *
+ * @docsCategory hooks
+ * @docsPage useChannel
+ * @docsWeight 0
+ * @since 3.3.0
+ */
+export function useChannel() {
+    const context = React.useContext(ChannelContext);
+    if (context === undefined) {
+        throw new Error('useChannel must be used within a ChannelProvider');
+    }
+    return context;
+}

package/src/lib/hooks/use-custom-field-config.ts

@@ -0,0 +1,27 @@
+import { usePermissions } from '@/vdb/hooks/use-permissions.js';
+import { CustomFieldConfig } from '@/vdb/providers/server-config.js';
+
+import { useServerConfig } from './use-server-config.js';
+
+/**
+ * @description
+ * Returns the custom field config for the given entity type (e.g. 'Product').
+ * Also filters out any custom fields that the current active user does not
+ * have permissions to access.
+ *
+ * @docsCategory hooks
+ * @since 3.4.0
+ */
+export function useCustomFieldConfig(entityType: string): CustomFieldConfig[] {
+    const serverConfig = useServerConfig();
+    const { hasPermissions } = usePermissions();
+    if (!serverConfig) {
+        return [];
+    }
+    const customFieldConfig = serverConfig.entityCustomFields.find(field => field.entityName === entityType);
+    return (
+        customFieldConfig?.customFields?.filter(config => {
+            return config.requiresPermission ? hasPermissions(config.requiresPermission) : true;
+        }) ?? []
+    );
+}

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-drag-and-drop.ts

@@ -0,0 +1,86 @@
+import { DragEndEvent, KeyboardSensor, PointerSensor, useSensor, useSensors } from '@dnd-kit/core';
+import { arrayMove, sortableKeyboardCoordinates } from '@dnd-kit/sortable';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+interface UseDragAndDropOptions<TData> {
+    data: TData[];
+    onReorder?: (oldIndex: number, newIndex: number, item: TData, allItems?: TData[]) => void | Promise<void>;
+    onError?: (error: Error) => void;
+    disabled?: boolean;
+}
+
+/**
+ * @description
+ * Provides the sensors and state management for drag and drop functionality.
+ *
+ *
+ * @docsCategory hooks
+ * @docsPage useDragAndDrop
+ * @docsWeight 0
+ * @since 3.3.0
+ */
+export function useDragAndDrop<TData = any>(options: UseDragAndDropOptions<TData>) {
+    const sensors = useSensors(
+        useSensor(PointerSensor),
+        useSensor(KeyboardSensor, {
+            coordinateGetter: sortableKeyboardCoordinates,
+        }),
+    );
+
+    const { data, onReorder, disabled = false } = options;
+
+    const [localData, setLocalData] = useState<TData[]>(data);
+    const [isReordering, setIsReordering] = useState(false);
+
+    // Update local data when data prop changes (but not during reordering)
+    useEffect(() => {
+        if (!isReordering) {
+            setLocalData(data);
+        }
+    }, [data, isReordering]);
+
+    const handleDragEnd = useCallback(
+        async (event: DragEndEvent) => {
+            const { active, over } = event;
+
+            if (!over || active.id === over.id || !onReorder || disabled) {
+                return;
+            }
+
+            const oldIndex = localData.findIndex(item => (item as { id: string }).id === active.id);
+            const newIndex = localData.findIndex(item => (item as { id: string }).id === over.id);
+
+            if (oldIndex === -1 || newIndex === -1) {
+                return;
+            }
+
+            // Optimistically update the UI
+            const originalState = [...localData];
+            const newData = arrayMove(localData, oldIndex, newIndex);
+            setLocalData(newData);
+            setIsReordering(true);
+
+            try {
+                // Call the user's onReorder callback with all items for context
+                await onReorder(oldIndex, newIndex, localData[oldIndex], localData);
+            } catch (error) {
+                // Revert on error
+                setLocalData(originalState);
+                options.onError?.(error as Error);
+            } finally {
+                setIsReordering(false);
+            }
+        },
+        [localData, onReorder, disabled],
+    );
+
+    const itemIds = useMemo(() => localData.map(item => (item as { id: string }).id), [localData]);
+
+    return {
+        sensors,
+        localData,
+        handleDragEnd,
+        itemIds,
+        isReordering,
+    };
+}

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

@@ -0,0 +1,37 @@
+import { extendDetailFormQuery } from '@/vdb/framework/document-extension/extend-detail-form-query.js';
+import { useLingui } from '@lingui/react/macro';
+import { DocumentNode } from 'graphql';
+import { useEffect, useMemo, useRef } from 'react';
+import { toast } from 'sonner';
+
+/**
+ * @description
+ * Extends a detail page query document with any registered extensions provided by
+ * the `extendDetailDocument` function for the given page.
+ */
+export function useExtendedDetailQuery<T extends DocumentNode>(detailQuery: T, pageId?: string) {
+    const hasShownError = useRef(false);
+    const { i18n } = useLingui();
+
+    const extendedDetailQuery = useMemo(() => {
+        if (!pageId || !detailQuery) {
+            return detailQuery;
+        }
+        const result = extendDetailFormQuery(detailQuery, pageId);
+        if (result.errorMessage && !hasShownError.current) {
+            // Show a user-friendly toast notification
+            toast.error(i18n.t('Query extension error'), {
+                description:
+                    result.errorMessage + '. ' + i18n.t('The page will continue with the default query.'),
+            });
+        }
+        return result.extendedQuery;
+    }, [detailQuery, pageId]);
+
+    // Reset error flag when dependencies change
+    useEffect(() => {
+        hasShownError.current = false;
+    }, [detailQuery, pageId]);
+
+    return extendedDetailQuery;
+}

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

@@ -0,0 +1,80 @@
+import { getListQueryDocuments } from '@/vdb/framework/data-table/data-table-extensions.js';
+import { extendDocument } from '@/vdb/framework/document-extension/extend-document.js';
+import { useLingui } from '@lingui/react/macro';
+import { DocumentNode } from 'graphql';
+import { useEffect, useMemo, useRef } from 'react';
+import { toast } from 'sonner';
+
+import { usePageBlock } from './use-page-block.js';
+import { usePage } from './use-page.js';
+
+/**
+ * @description
+ * Extends the given list query document with additional fields that can be
+ * supplied via the Dashboard Extension API.
+ */
+export function useExtendedListQuery<T extends DocumentNode>(listQuery: T) {
+    const { pageId } = usePage();
+    const { blockId } = usePageBlock() ?? {};
+    const { i18n } = useLingui();
+    const listQueryExtensions = pageId && blockId ? getListQueryDocuments(pageId, blockId) : [];
+    const hasShownError = useRef(false);
+
+    const extendedListQuery = useMemo(() => {
+        let result: T = listQuery;
+
+        try {
+            result = listQueryExtensions.reduce(
+                (acc, extension) => extendDocument(acc, extension),
+                listQuery,
+            ) as T;
+        } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Continue with the original query instead of the extended one
+            result = listQuery;
+
+            // Store error for useEffect to handle
+            if (error && !hasShownError.current) {
+                hasShownError.current = true;
+
+                // Provide a helpful error message based on the error type
+                let errorMessageText = i18n.t('Failed to extend query document');
+                if (error.message.includes('Extension query must have at least one top-level field')) {
+                    errorMessageText = i18n.t(
+                        'Query extension is invalid: must have at least one top-level field',
+                    );
+                } else if (error.message.includes('The query extension must extend the')) {
+                    errorMessageText = i18n.t('Query extension mismatch: ') + error.message;
+                } else if (error.message.includes('Syntax Error')) {
+                    errorMessageText = i18n.t('Query extension contains invalid GraphQL syntax');
+                } else {
+                    errorMessageText = i18n.t('Query extension error: ') + error.message;
+                }
+
+                // Log the error and continue with the original query
+                // eslint-disable-next-line no-console
+                console.warn(`${errorMessageText}. Continuing with original query.`, {
+                    pageId,
+                    blockId,
+                    extensionsCount: listQueryExtensions.length,
+                    error: error.message,
+                });
+
+                // Show a user-friendly toast notification
+                toast.error(i18n.t('Query extension error'), {
+                    description:
+                        errorMessageText + '. ' + i18n.t('The page will continue with the default query.'),
+                });
+            }
+        }
+
+        return result;
+    }, [listQuery, listQueryExtensions, pageId, blockId]);
+
+    // Reset error flag when dependencies change
+    useEffect(() => {
+        hasShownError.current = false;
+    }, [listQuery, listQueryExtensions, pageId, blockId]);
+
+    return extendedListQuery;
+}

package/src/lib/hooks/use-floating-bulk-actions.ts

@@ -0,0 +1,83 @@
+import { useEffect, useState } from 'react';
+
+interface FloatingPosition {
+    bottom: string;
+    left: string;
+}
+
+interface UseFloatingBulkActionsOptions {
+    selectionCount: number;
+    containerSelector: string;
+    bufferDistance?: number;
+    bottomOffset?: number;
+}
+
+/**
+ * Common logic used to power floating the bulk action component used in
+ * data tables and in the asset gallery.
+ */
+export function useFloatingBulkActions({
+    selectionCount,
+    containerSelector,
+    bufferDistance = 80,
+    bottomOffset = 10,
+}: Readonly<UseFloatingBulkActionsOptions>) {
+    const [position, setPosition] = useState<FloatingPosition>({ bottom: '2.5rem', left: '50%' });
+    const [isPositioned, setIsPositioned] = useState(false);
+
+    useEffect(() => {
+        if (selectionCount === 0) {
+            setIsPositioned(false);
+            return;
+        }
+
+        const updatePosition = () => {
+            // Find the container in the document
+            const container = document.querySelector(containerSelector) as HTMLElement;
+            if (!container) return;
+
+            const containerRect = container.getBoundingClientRect();
+            const viewportHeight = window.innerHeight;
+
+            // Check if container bottom is visible in viewport
+            const containerBottom = containerRect.bottom;
+            const isContainerFullyVisible = containerBottom <= viewportHeight - bufferDistance;
+
+            // Calculate horizontal center
+            const containerLeft = containerRect.left;
+            const containerWidth = containerRect.width;
+            const centerX = containerLeft + containerWidth / 2;
+
+            if (isContainerFullyVisible) {
+                // Position relative to container bottom
+                setPosition({
+                    bottom: `${viewportHeight - containerBottom + bottomOffset}px`,
+                    left: `${centerX}px`,
+                });
+            } else {
+                // Position relative to viewport bottom, centered in container
+                setPosition({
+                    bottom: '2.5rem',
+                    left: `${centerX}px`,
+                });
+            }
+
+            setIsPositioned(true);
+        };
+
+        updatePosition();
+        window.addEventListener('scroll', updatePosition);
+        window.addEventListener('resize', updatePosition);
+
+        return () => {
+            window.removeEventListener('scroll', updatePosition);
+            window.removeEventListener('resize', updatePosition);
+        };
+    }, [selectionCount, containerSelector, bufferDistance]);
+
+    return {
+        position,
+        isPositioned,
+        shouldShow: selectionCount > 0 && isPositioned,
+    };
+}

package/src/lib/hooks/use-grouped-permissions.ts

@@ -0,0 +1,55 @@
+import { ServerConfig } from '@/vdb/providers/server-config.js';
+import { useMemo } from 'react';
+
+import { useServerConfig } from './use-server-config.js';
+
+export function useGroupedPermissions() {
+    const serverConfig = useServerConfig();
+    const permissionDefinitions = serverConfig?.permissions ?? [];
+    const extractCrudDescription = (def: ServerConfig['permissions'][number]): string => {
+        return def.description.replace(/Grants permission to [\w]+/, 'Grants permissions on');
+    };
+
+    const groupedPermissions = useMemo(() => {
+        const crudGroups = new Map<string, ServerConfig['permissions']>();
+        const nonCrud: ServerConfig['permissions'] = [];
+        const crudRe = /^(Create|Read|Update|Delete)([a-zA-Z]+)$/;
+
+        for (const def of permissionDefinitions) {
+            const isCrud = crudRe.test(def.name);
+            if (isCrud) {
+                const groupName = def.name.match(crudRe)?.[2];
+                if (groupName) {
+                    const existing = crudGroups.get(groupName);
+                    if (existing) {
+                        existing.push(def);
+                    } else {
+                        crudGroups.set(groupName, [def]);
+                    }
+                }
+            } else if (def.assignable) {
+                nonCrud.push(def);
+            }
+        }
+
+        return [
+            ...nonCrud.map(d => ({
+                label: d.name,
+                description: d.description,
+                permissions: [d],
+            })),
+            ...Array.from(crudGroups.entries()).map(([label, defs]) => ({
+                label,
+                description: extractCrudDescription(defs[0]),
+                permissions: defs.sort((a, b) => a.name.localeCompare(b.name)),
+            })),
+        ]
+            .sort((a, b) => a.label.localeCompare(b.label))
+            .map(d => ({
+                ...d,
+                id: `section-${d.label.toLowerCase().replace(/ /g, '-')}`,
+            }));
+    }, [permissionDefinitions]);
+
+    return groupedPermissions;
+}