@vendure/dashboard 3.4.2-master-202509081248 → 3.4.2-master-202509110229

package/src/lib/components/layout/generated-breadcrumbs.tsx

@@ -5,9 +5,11 @@ import {
     BreadcrumbList,
     BreadcrumbSeparator,
 } from '@/vdb/components/ui/breadcrumb.js';
-import { Link, useRouterState } from '@tanstack/react-router';
+import { Link, useRouter, useRouterState } from '@tanstack/react-router';
 import * as React from 'react';
 import { Fragment } from 'react';
+import { getNavMenuConfig } from '@/vdb/framework/nav-menu/nav-menu-extensions.js';
+import type { NavMenuItem, NavMenuSection } from '@/vdb/framework/nav-menu/nav-menu-extensions.js';
 
 export interface BreadcrumbPair {
     label: string | React.ReactElement;
@@ -20,54 +22,112 @@ export type PageBreadcrumb = BreadcrumbPair | BreadcrumbShorthand;
 
 export function GeneratedBreadcrumbs() {
     const matches = useRouterState({ select: s => s.matches });
-    const breadcrumbs: BreadcrumbPair[] = matches
-        .filter(match => match.loaderData?.breadcrumb)
-        .map(({ pathname, loaderData }) => {
-            if (typeof loaderData.breadcrumb === 'string') {
-                return {
-                    label: loaderData.breadcrumb,
-                    path: pathname,
-                };
-            }
-            if (Array.isArray(loaderData.breadcrumb)) {
-                return loaderData.breadcrumb.map((breadcrumb: PageBreadcrumb) => {
-                    if (typeof breadcrumb === 'string') {
-                        return {
-                            label: breadcrumb,
-                            path: pathname,
-                        };
-                    } else if (React.isValidElement(breadcrumb)) {
-                        return {
-                            label: breadcrumb,
-                            path: pathname,
-                        };
-                    } else {
-                        return {
-                            label: breadcrumb.label,
-                            path: breadcrumb.path,
-                        };
-                    }
-                });
-            }
-            if (typeof loaderData.breadcrumb === 'function') {
-                return {
-                    label: loaderData.breadcrumb(),
-                    path: pathname,
-                };
+    const currentPath = useRouterState({ select: s => s.location.pathname });
+    const router = useRouter();
+    const navMenuConfig = getNavMenuConfig();
+    const basePath = router.basepath || '';
+
+    const normalizeBreadcrumb = (breadcrumb: any, pathname: string): BreadcrumbPair[] => {
+        if (typeof breadcrumb === 'string') {
+            return [{ label: breadcrumb, path: pathname }];
+        }
+        if (React.isValidElement(breadcrumb)) {
+            return [{ label: breadcrumb, path: pathname }];
+        }
+        if (typeof breadcrumb === 'function') {
+            return [{ label: breadcrumb(), path: pathname }];
+        }
+        if (Array.isArray(breadcrumb)) {
+            return breadcrumb.map((crumb: PageBreadcrumb) => {
+                if (typeof crumb === 'string' || React.isValidElement(crumb)) {
+                    return { label: crumb, path: pathname };
+                }
+                return { label: crumb.label, path: crumb.path };
+            });
+        }
+        return [];
+    };
+
+    const rawCrumbs: BreadcrumbPair[] = React.useMemo(() => {
+        return matches
+            .filter(match => match.loaderData?.breadcrumb)
+            .flatMap(({ pathname, loaderData }) => 
+                normalizeBreadcrumb(loaderData.breadcrumb, pathname)
+            );
+    }, [matches]);
+
+    const isBaseRoute = (p: string) => p === basePath || p === `${basePath}/`;
+    const pageCrumbs: BreadcrumbPair[] = rawCrumbs.filter(c => !isBaseRoute(c.path));
+
+    const normalizePath = (path: string): string => {
+        const normalizedPath = basePath && path.startsWith(basePath) ? path.slice(basePath.length) : path;
+        return normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`;
+    };
+
+    const pathMatches = (cleanPath: string, rawUrl?: string): boolean => {
+        if (!rawUrl) return false;
+        const strip = (p: string) => (p !== '/' && p.endsWith('/') ? p.slice(0, -1) : p);
+        const p = strip(cleanPath);
+        const u = strip(rawUrl);
+        return p === u || p.startsWith(`${u}/`);
+    };
+
+    const checkSectionItems = (
+        section: NavMenuSection | NavMenuItem,
+        cleanPath: string,
+    ): BreadcrumbPair | undefined => {
+        if (!('items' in section) || !Array.isArray(section.items)) {
+            return undefined;
+        }
+
+        for (const item of section.items) {
+            if (!item?.url) continue;
+            if (pathMatches(cleanPath, item.url)) {
+                return { label: section.title, path: item.url };
             }
-            if (React.isValidElement(loaderData.breadcrumb)) {
-                return {
-                    label: loaderData.breadcrumb,
-                    path: pathname,
-                };
+        }
+        return undefined;
+    };
+
+    const checkDirectSection = (
+        section: NavMenuSection | NavMenuItem,
+        cleanPath: string,
+    ): BreadcrumbPair | undefined => {
+        if ('url' in section && section.url && pathMatches(cleanPath, section.url)) {
+            return { label: section.title, path: section.url };
+        }
+        return undefined;
+    };
+
+    const findSectionCrumb = (path: string): BreadcrumbPair | undefined => {
+        const cleanPath = normalizePath(path);
+        const sections: Array<NavMenuSection | NavMenuItem> = navMenuConfig?.sections ?? [];
+        if (sections.length === 0) return undefined;
+
+        for (const section of sections) {
+            const result = checkSectionItems(section, cleanPath) || checkDirectSection(section, cleanPath);
+            if (result) {
+                return result;
             }
-        })
-        .flat();
+        }
+        return undefined;
+    };
+
+    const sectionCrumb = React.useMemo(
+        () => findSectionCrumb(currentPath),
+        [currentPath, basePath, navMenuConfig],
+    );
+    const breadcrumbs: BreadcrumbPair[] = React.useMemo(() => {
+        const arr = sectionCrumb ? [sectionCrumb, ...pageCrumbs] : pageCrumbs;
+        return arr.filter((c, i, self) =>
+            self.findIndex(x => x.path === c.path && x.label === c.label) === i,
+        );
+    }, [sectionCrumb, pageCrumbs]);
     return (
         <Breadcrumb>
             <BreadcrumbList>
                 {breadcrumbs.map(({ label, path }, index, arr) => (
-                    <Fragment key={index}>
+                    <Fragment key={`${path}-${index}`}>
                         <BreadcrumbItem className="hidden md:block">
                             <BreadcrumbLink asChild>
                                 <Link to={path}>{label}</Link>

package/src/lib/components/shared/asset/asset-gallery.tsx

@@ -71,6 +71,13 @@ const AssetType = {
 
 export type Asset = AssetFragment;
 
+/**
+ * @description
+ * Props for the {@link AssetGallery} component.
+ * 
+ * @docsCategory components
+ * @docsPage AssetGallery
+ */
 export interface AssetGalleryProps {
     onSelect?: (assets: Asset[]) => void;
     selectable?: boolean;
@@ -82,16 +89,67 @@ export interface AssetGalleryProps {
      * If set to 'manual', multiple selection will occur only if the user holds down the control/cmd key.
      */
     multiSelect?: 'auto' | 'manual';
+    /**
+     * @description
+     * The initial assets that should be selected.
+     */
     initialSelectedAssets?: Asset[];
+    /**
+     * @description
+     * The number of assets to display per page.
+     */
     pageSize?: number;
+    /**
+     * @description
+     * Whether the gallery should have a fixed height.
+     */
     fixedHeight?: boolean;
+    /**
+     * @description
+     * Whether the gallery should show a header.
+     */
     showHeader?: boolean;
+    /**
+     * @description
+     * The class name to apply to the gallery.
+     */
     className?: string;
+    /**
+     * @description
+     * The function to call when files are dropped.
+     */
     onFilesDropped?: (files: File[]) => void;
+    /**
+     * @description
+     * The bulk actions to display in the gallery.
+     */
     bulkActions?: AssetBulkAction[];
+    /**
+     * @description
+     * Whether the gallery should display bulk actions.
+     */
     displayBulkActions?: boolean;
 }
 
+/**
+ * @description
+ * A component for displaying a gallery of assets.
+ * 
+ * @example
+ * ```tsx
+ *  <AssetGallery
+        onSelect={handleAssetSelect}
+        multiSelect="manual"
+        initialSelectedAssets={initialSelectedAssets}
+        fixedHeight={false}
+        displayBulkActions={false}
+    />
+ * ```
+ *
+ * @docsCategory components
+ * @docsPage AssetGallery
+ * @docsWeight 0
+ */
 export function AssetGallery({
     onSelect,
     selectable = true,

package/src/lib/components/shared/asset/asset-picker-dialog.tsx

@@ -9,15 +9,54 @@ import {
 import { useState } from 'react';
 import { Asset, AssetGallery } from './asset-gallery.js';
 
+/**
+ * @description
+ * Props for the {@link AssetPickerDialog} component.
+ * 
+ * @docsCategory components
+ * @docsPage AssetPickerDialog
+ */
 interface AssetPickerDialogProps {
+    /**
+     * @description
+     * Whether the dialog is open.
+     */
     open: boolean;
+    /**
+     * @description
+     * The function to call when the dialog is closed.
+     */
     onClose: () => void;
+    /**
+     * @description
+     * The function to call when assets are selected.
+     */
     onSelect: (assets: Asset[]) => void;
+    /**
+     * @description
+     * Whether multiple assets can be selected.
+     */
     multiSelect?: boolean;
+    /**
+     * @description
+     * The initial assets that should be selected.
+     */
     initialSelectedAssets?: Asset[];
+    /**
+     * @description
+     * The title of the dialog.
+     */
     title?: string;
 }
 
+/**
+ * @description
+ * A dialog which allows the creation and selection of assets.
+ * 
+ * @docsCategory components
+ * @docsPage AssetPickerDialog
+ * @docsWeight 0
+ */
 export function AssetPickerDialog({
     open,
     onClose,

package/src/lib/components/shared/detail-page-button.tsx

@@ -3,46 +3,32 @@ import { ChevronRight } from 'lucide-react';
 import { Button } from '../ui/button.js';
 
 /**
+ * @description
  * DetailPageButton is a reusable navigation component designed to provide consistent UX
  * across list views when linking to detail pages. It renders as a ghost button with
  * a chevron indicator, making it easy for users to identify clickable links that
  * navigate to detail views.
  *
- * @component
  * @example
+ * ```tsx
  * // Basic usage with ID (relative navigation)
  * <DetailPageButton id="123" label="Product Name" />
+ * 
  *
  * @example
+ * ```tsx
  * // Custom href with search params
  * <DetailPageButton
  *   href="/products/detail/456"
  *   label="Custom Product"
  *   search={{ tab: 'variants' }}
  * />
+ * ```
  *
- * @example
- * // Disabled state
- * <DetailPageButton
- *   id="789"
- *   label="Unavailable Item"
- *   disabled={true}
- * />
- *
- * @param {Object} props - Component props
- * @param {string|React.ReactNode} props.label - The text or content to display in the button
- * @param {string} [props.id] - The ID for relative navigation (creates href as `./${id}`)
- * @param {string} [props.href] - Custom href for navigation (takes precedence over id)
- * @param {boolean} [props.disabled=false] - Whether the button is disabled (prevents navigation)
- * @param {Record<string, string>} [props.search] - Search parameters to include in the navigation
- *
- * @returns {React.ReactElement} A styled button component that navigates to detail pages
  *
- * @remarks
- * - Uses TanStack Router's Link component for client-side navigation
- * - Includes a chevron icon (hidden when disabled) to indicate navigation
- * - Preloading is disabled by default for performance optimization
- * - Styled as a ghost button variant for subtle, consistent appearance
+ * @docsCategory components
+ * @docsPage DetailPageButton
+ * @since 3.4.0
  */
 export function DetailPageButton({
     id,

package/src/lib/components/shared/facet-value-chip.tsx

@@ -20,6 +20,13 @@ interface FacetValueChipProps {
     onRemove?: (id: string) => void;
 }
 
+/**
+ * @description
+ * A component for displaying a facet value as a chip.
+ *
+ * @docsCategory components
+ * @since 3.4.0
+ */
 export function FacetValueChip({
     facetValue,
     removable = true,

package/src/lib/components/shared/facet-value-selector.tsx

@@ -29,10 +29,51 @@ export interface Facet {
     code: string;
 }
 
+/**
+ * @description
+ * A component for selecting facet values.
+ *
+ * @docsCategory components
+ * @docsPage FacetValueSelector
+ * @since 3.4.0
+ */
 interface FacetValueSelectorProps {
+    /**
+     * @description
+     * The function to call when a facet value is selected.
+     * 
+     * The `value` will have the following structure:
+     * 
+     * ```ts
+     * {
+     *     id: string;
+     *     name: string;
+     *     code: string;
+     *     facet: {
+     *         id: string;
+     *         name: string;
+     *         code: string;
+     *     };
+     * }
+     * ```
+     */
     onValueSelect: (value: FacetValue) => void;
+    /**
+     * @description
+     * Whether the selector is disabled.
+     */
     disabled?: boolean;
+    /**
+     * @description
+     * The placeholder text for the selector.
+     */
     placeholder?: string;
+    /**
+     * @description
+     * The number of facet values to display per page.
+     * 
+     * @default 4
+     */
     pageSize?: number;
 }
 
@@ -85,6 +126,20 @@ const getFacetValuesForFacetDocument = graphql(`
     }
 `);
 
+/**
+ * @description
+ * A component for selecting facet values.
+ * 
+ * @example
+ * ```tsx
+ * <FacetValueSelector onValueSelect={onValueSelectHandler} disabled={disabled} />
+ * ```
+ *
+ * @docsCategory components
+ * @docsPage FacetValueSelector
+ * @docsWeight 0
+ * @since 3.4.0
+ */
 export function FacetValueSelector({
     onValueSelect,
     disabled,

package/src/lib/components/shared/form-field-wrapper.tsx

@@ -3,11 +3,27 @@ import { LocationWrapper } from '@/vdb/framework/layout-engine/location-wrapper.
 import { FieldPath, FieldValues } from 'react-hook-form';
 import { FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage } from '../ui/form.js';
 
+/**
+ * @description
+ * The props for the FormFieldWrapper component.
+ *
+ * @docsCategory form-components
+ * @docsPage FormFieldWrapper
+ * @since 3.4.0
+ */
 export type FormFieldWrapperProps<
     TFieldValues extends FieldValues = FieldValues,
     TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
 > = React.ComponentProps<typeof FormField<TFieldValues, TName>> & {
+    /**
+     * @description
+     * The label for the form field.
+     */
     label?: React.ReactNode;
+    /**
+     * @description
+     * The description for the form field.
+     */
     description?: React.ReactNode;
     /**
      * @description
@@ -15,11 +31,46 @@ export type FormFieldWrapperProps<
      * If false, the form control will not be rendered.
      * This is useful when you want to render the form control in a custom way, e.g. for <Select/> components,
      * where the FormControl needs to nested in the root component.
+     *
      * @default true
      */
     renderFormControl?: boolean;
 };
 
+/**
+ * @description
+ * This is a wrapper that can be used in all forms to wrap the actual form control, and provide a label, description and error message.
+ * 
+ * Use this instead of the default Shadcn FormField (etc.) components, as it also supports
+ * overridden form components.
+ * 
+ * @example
+ * ```tsx
+ * <PageBlock column="main" blockId="main-form">
+ *     <DetailFormGrid>
+ *         <FormFieldWrapper
+ *             control={form.control}
+ *             name="description"
+ *             label={<Trans>Description</Trans>}
+ *             render={({ field }) => <Input {...field} />}
+ *         />
+ *         <FormFieldWrapper
+ *             control={form.control}
+ *             name="code"
+ *             label={<Trans>Code</Trans>}
+ *             render={({ field }) => <Input {...field} />}
+ *         />
+ *     </DetailFormGrid>
+ * </PageBlock>
+ * ```
+ * 
+ * If you are dealing with translatable fields, use the {@link TranslatableFormFieldWrapper} component instead.
+ *
+ * @docsCategory form-components
+ * @docsPage FormFieldWrapper
+ * @docsWeight 0
+ * @since 3.4.0
+ */
 export function FormFieldWrapper<
     TFieldValues extends FieldValues = FieldValues,
     TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,