@leandrosk/dashboard 3.5.5

package/src/lib/hooks/use-facet-value-browser.ts

@@ -0,0 +1,292 @@
+import { api } from '@/vdb/graphql/api.js';
+import { graphql } from '@/vdb/graphql/graphql.js';
+import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
+import { useDebounce } from '@uidotdev/usehooks';
+import React, { useState } from 'react';
+
+export interface FacetValue {
+    id: string;
+    name: string;
+    code: string;
+    facet: Facet;
+}
+
+export interface Facet {
+    id: string;
+    name: string;
+    code: string;
+}
+
+const getFacetValueListDocument = graphql(`
+    query GetFacetValueList($options: FacetValueListOptions) {
+        facetValues(options: $options) {
+            items {
+                id
+                name
+                code
+                facet {
+                    id
+                    name
+                    code
+                }
+            }
+            totalItems
+        }
+    }
+`);
+
+const getFacetListDocument = graphql(`
+    query GetFacetList($options: FacetListOptions) {
+        facets(options: $options) {
+            items {
+                id
+                name
+                code
+            }
+            totalItems
+        }
+    }
+`);
+
+const getFacetValuesForFacetDocument = graphql(`
+    query GetFacetValuesForFacet($options: FacetValueListOptions) {
+        facetValues(options: $options) {
+            items {
+                id
+                name
+                code
+                facet {
+                    id
+                    name
+                    code
+                }
+            }
+            totalItems
+        }
+    }
+`);
+
+export { getFacetValueListDocument };
+
+export interface UseFacetValueBrowserOptions {
+    /** Number of items per page for infinite scroll. @default 10 */
+    pageSize?: number;
+    /** Whether to start in browse mode. @default false */
+    initialBrowseMode?: boolean;
+    /** Query key prefix to avoid cache collisions between consumers. @default 'facetValues' */
+    queryKeyPrefix?: string;
+}
+
+export interface UseFacetValueBrowserReturn {
+    // Search state
+    searchTerm: string;
+    setSearchTerm: (value: string) => void;
+    debouncedSearch: string;
+    minSearchLength: number;
+
+    // Browse/expand state
+    browseMode: boolean;
+    setBrowseMode: (value: boolean) => void;
+    expandedFacetId: string | null;
+    setExpandedFacetId: (id: string | null) => void;
+
+    // Derived data
+    facetValues: FacetValue[];
+    facets: Facet[];
+    expandedFacetValues: FacetValue[];
+    expandedFacetName: string | undefined;
+    facetGroups: Record<string, FacetValue[]>;
+
+    // Loading states
+    isLoading: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingNextFacetsPage: boolean;
+    isLoadingExpandedFacet: boolean;
+
+    // Pagination
+    hasNextPage: boolean;
+    hasNextFacetsPage: boolean;
+
+    // Infinite scroll
+    handleScroll: (e: React.UIEvent<HTMLDivElement>) => void;
+
+    // Reset all state
+    reset: () => void;
+}
+
+/**
+ * @description
+ * A hook that encapsulates the data-fetching, pagination, search, and browse-mode logic
+ * for navigating facets and facet values. Used by both `FacetValueSelector` (single-select)
+ * and `FacetValueFacetedFilter` (multi-select for list filtering).
+ *
+ * @docsCategory hooks
+ * @since 3.6.0
+ */
+export function useFacetValueBrowser(options?: UseFacetValueBrowserOptions): UseFacetValueBrowserReturn {
+    const { pageSize = 10, initialBrowseMode = false, queryKeyPrefix = 'facetValues' } = options ?? {};
+    const minSearchLength = 1;
+
+    const [searchTerm, setSearchTerm] = useState('');
+    const [expandedFacetId, setExpandedFacetId] = useState<string | null>(null);
+    const [browseMode, setBrowseMode] = useState(initialBrowseMode);
+    const debouncedSearch = useDebounce(searchTerm, 200);
+
+    // Search facet values by name
+    const { data: facetValueData, isLoading: isLoadingFacetValues } = useQuery({
+        queryKey: [queryKeyPrefix, debouncedSearch],
+        queryFn: () => {
+            if (debouncedSearch.length < minSearchLength) {
+                return { facetValues: { items: [], totalItems: 0 } };
+            }
+            return api.query(getFacetValueListDocument, {
+                options: {
+                    filter: { name: { contains: debouncedSearch } },
+                    take: 100,
+                },
+            });
+        },
+        enabled: debouncedSearch.length >= minSearchLength && !expandedFacetId,
+    });
+
+    // Search facets by name
+    const { data: facetSearchData, isLoading: isLoadingFacetSearch } = useQuery({
+        queryKey: [queryKeyPrefix, 'facets', debouncedSearch],
+        queryFn: () => {
+            if (debouncedSearch.length < minSearchLength) {
+                return { facets: { items: [], totalItems: 0 } };
+            }
+            return api.query(getFacetListDocument, {
+                options: {
+                    filter: { name: { contains: debouncedSearch } },
+                    take: 100,
+                },
+            });
+        },
+        enabled: !browseMode && debouncedSearch.length >= minSearchLength && !expandedFacetId,
+    });
+
+    // Browse facets with pagination
+    const {
+        data: facetBrowseData,
+        isLoading: isLoadingFacetBrowse,
+        fetchNextPage: fetchNextFacetsPage,
+        hasNextPage: hasNextFacetsPage,
+        isFetchingNextPage: isFetchingNextFacetsPage,
+    } = useInfiniteQuery({
+        queryKey: [queryKeyPrefix, 'facets', 'browse'],
+        queryFn: async ({ pageParam = 0 }) => {
+            const response = await api.query(getFacetListDocument, {
+                options: {
+                    filter: {},
+                    sort: { name: 'ASC' },
+                    skip: pageParam * pageSize,
+                    take: pageSize,
+                },
+            });
+            return response.facets;
+        },
+        getNextPageParam: (lastPage, allPages) => {
+            if (!lastPage) return undefined;
+            const totalFetched = allPages.length * pageSize;
+            return totalFetched < lastPage.totalItems ? allPages.length : undefined;
+        },
+        enabled: browseMode && !expandedFacetId,
+        initialPageParam: 0,
+    });
+
+    // Browse facet values within a specific facet
+    const {
+        data: expandedFacetData,
+        isLoading: isLoadingExpandedFacet,
+        fetchNextPage,
+        hasNextPage,
+        isFetchingNextPage,
+    } = useInfiniteQuery({
+        queryKey: [queryKeyPrefix, expandedFacetId, 'infinite'],
+        queryFn: async ({ pageParam = 0 }) => {
+            if (!expandedFacetId) return null;
+            const response = await api.query(getFacetValuesForFacetDocument, {
+                options: {
+                    filter: { facetId: { eq: expandedFacetId } },
+                    sort: { code: 'ASC' },
+                    skip: pageParam * pageSize,
+                    take: pageSize,
+                },
+            });
+            return response.facetValues;
+        },
+        getNextPageParam: (lastPage, allPages) => {
+            if (!lastPage) return undefined;
+            const totalFetched = allPages.length * pageSize;
+            return totalFetched < lastPage.totalItems ? allPages.length : undefined;
+        },
+        enabled: !!expandedFacetId,
+        initialPageParam: 0,
+    });
+
+    // Derived data
+    const facetValues = (facetValueData?.facetValues.items ?? []) as FacetValue[];
+    const facets = browseMode
+        ? ((facetBrowseData?.pages.flatMap(page => page?.items ?? []) ?? []) as Facet[])
+        : ((facetSearchData?.facets.items ?? []) as Facet[]);
+    const expandedFacetValues = (expandedFacetData?.pages.flatMap(page => page?.items ?? []) ??
+        []) as FacetValue[];
+    const expandedFacetName = expandedFacetValues[0]?.facet.name;
+
+    // Group search results by facet
+    const facetGroups = facetValues.reduce<Record<string, FacetValue[]>>((groups, fv) => {
+        const facetId = fv.facet.id;
+        if (!groups[facetId]) {
+            groups[facetId] = [];
+        }
+        groups[facetId].push(fv);
+        return groups;
+    }, {});
+
+    const isLoading =
+        isLoadingFacetValues || isLoadingFacetSearch || isLoadingFacetBrowse || isLoadingExpandedFacet;
+
+    const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
+        const target = e.currentTarget;
+        const scrolledToBottom = Math.abs(target.scrollHeight - target.clientHeight - target.scrollTop) < 1;
+        if (scrolledToBottom && !isFetchingNextPage) {
+            if (expandedFacetId && hasNextPage) {
+                void fetchNextPage();
+            }
+            if (browseMode && !expandedFacetId && hasNextFacetsPage) {
+                void fetchNextFacetsPage();
+            }
+        }
+    };
+
+    const reset = () => {
+        setSearchTerm('');
+        setExpandedFacetId(null);
+        setBrowseMode(initialBrowseMode);
+    };
+
+    return {
+        searchTerm,
+        setSearchTerm,
+        debouncedSearch,
+        minSearchLength,
+        browseMode,
+        setBrowseMode,
+        expandedFacetId,
+        setExpandedFacetId,
+        facetValues,
+        facets,
+        expandedFacetValues,
+        expandedFacetName,
+        facetGroups,
+        isLoading,
+        isFetchingNextPage,
+        isFetchingNextFacetsPage,
+        isLoadingExpandedFacet,
+        hasNextPage: hasNextPage ?? false,
+        hasNextFacetsPage: hasNextFacetsPage ?? false,
+        handleScroll,
+        reset,
+    };
+}

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;
+}

package/src/lib/hooks/use-job-queue-polling.ts

@@ -0,0 +1,160 @@
+import { api } from '@/vdb/graphql/api.js';
+import { graphql } from '@/vdb/graphql/graphql.js';
+import { useQuery } from '@tanstack/react-query';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+const JOB_LOOKBACK_MS = 5000; // Look back 5 seconds to catch jobs created before mutation returned
+const MAX_POLLING_TIMEOUT_MS = 30000;
+const INITIAL_POLL_INTERVAL_MS = 500;
+const MAX_POLL_INTERVAL_MS = 4000;
+const STORAGE_KEY_PREFIX = 'job-queue-polling:';
+
+interface StoredPollingState {
+    startTime: string;
+    expiresAt: number;
+}
+
+const jobListForPollingDocument = graphql(`
+    query JobListForPolling($options: JobListOptions) {
+        jobs(options: $options) {
+            items {
+                id
+                createdAt
+                state
+            }
+            totalItems
+        }
+    }
+`);
+
+const getStorageKey = (queueName: string) => `${STORAGE_KEY_PREFIX}${queueName}`;
+const getStoredState = (queueName: string) => {
+    try {
+        const stored = sessionStorage.getItem(getStorageKey(queueName));
+        if (stored) {
+            return JSON.parse(stored) as StoredPollingState;
+        }
+    } catch {
+        // Ignore parsing errors
+    }
+    return null;
+};
+const setStoredState = (queueName: string, state: StoredPollingState) =>
+    sessionStorage.setItem(getStorageKey(queueName), JSON.stringify(state));
+const clearStoredState = (queueName: string) => sessionStorage.removeItem(getStorageKey(queueName));
+
+/**
+ * Hook to poll a job queue until jobs complete.
+ * Waits for jobs created after polling starts to settle before calling onComplete.
+ *
+ * Polling state is persisted in sessionStorage, allowing it to survive navigation
+ * (e.g., after creating an entity) and page refresh while maintaining the correct
+ * time window for finding relevant jobs.
+ */
+export function useJobQueuePolling(queueName: string, onComplete: () => void) {
+    const [isPolling, setIsPolling] = useState(false);
+    const [pollCount, setPollCount] = useState(0);
+    const startTimeRef = useRef<string | null>(null);
+    const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const onCompleteRef = useRef(onComplete);
+    const hasResumedRef = useRef(false);
+
+    useEffect(() => {
+        onCompleteRef.current = onComplete;
+    }, [onComplete]);
+
+    // On mount, check for pending polling state
+    useEffect(() => {
+        if (hasResumedRef.current) return;
+        hasResumedRef.current = true;
+
+        const stored = getStoredState(queueName);
+        if (stored && Date.now() < stored.expiresAt) {
+            startTimeRef.current = stored.startTime;
+            setPollCount(0);
+            setIsPolling(true);
+
+            const remainingTime = stored.expiresAt - Date.now();
+            timeoutRef.current = setTimeout(() => {
+                setIsPolling(false);
+                startTimeRef.current = null;
+                clearStoredState(queueName);
+                onCompleteRef.current();
+            }, remainingTime);
+        } else if (stored) {
+            clearStoredState(queueName);
+        }
+    }, [queueName]);
+
+    // Calculate exponential backoff interval
+    const pollInterval = isPolling
+        ? Math.min(INITIAL_POLL_INTERVAL_MS * Math.pow(1.75, pollCount), MAX_POLL_INTERVAL_MS)
+        : false;
+
+    const { data: jobsData } = useQuery({
+        queryKey: ['jobQueuePolling', queueName],
+        queryFn: () => {
+            setPollCount(c => c + 1);
+            return api.query(jobListForPollingDocument, {
+                options: {
+                    filter: { queueName: { eq: queueName } },
+                    sort: { createdAt: 'DESC' as const },
+                    take: 10,
+                },
+            });
+        },
+        enabled: isPolling,
+        refetchInterval: pollInterval,
+    });
+
+    // Detect job completion
+    useEffect(() => {
+        const startTime = startTimeRef.current;
+        if (!isPolling || !startTime) return;
+
+        const relevantJobs = jobsData?.jobs.items.filter(j => j.createdAt >= startTime) ?? [];
+        const hasSettledJob =
+            relevantJobs.length > 0 &&
+            relevantJobs.every(j => j.state !== 'PENDING' && j.state !== 'RUNNING' && j.state !== 'RETRYING');
+
+        if (hasSettledJob) {
+            setIsPolling(false);
+            startTimeRef.current = null;
+            clearStoredState(queueName);
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+                timeoutRef.current = null;
+            }
+            onCompleteRef.current();
+        }
+    }, [jobsData, isPolling, queueName]);
+
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current) clearTimeout(timeoutRef.current);
+        };
+    }, []);
+
+    const startPolling = useCallback(() => {
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+
+        const startTime = new Date(Date.now() - JOB_LOOKBACK_MS).toISOString();
+        const expiresAt = Date.now() + MAX_POLLING_TIMEOUT_MS;
+
+        // Store in sessionStorage so polling can resume after navigation
+        setStoredState(queueName, { startTime, expiresAt });
+
+        startTimeRef.current = startTime;
+        setPollCount(0);
+        setIsPolling(true);
+
+        timeoutRef.current = setTimeout(() => {
+            setIsPolling(false);
+            startTimeRef.current = null;
+            clearStoredState(queueName);
+            onCompleteRef.current();
+        }, MAX_POLLING_TIMEOUT_MS);
+    }, [queueName]);
+
+    return { isPolling, startPolling };
+}