@vendure/dashboard 3.4.2-master-202509090229 → 3.4.2

package/src/lib/components/data-input/checkbox-input.tsx

@@ -2,6 +2,13 @@ import { Checkbox } from '../ui/checkbox.js';
 import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-engine-types.js';
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 
+/**
+ * @description
+ * Displays a boolean value as a checkbox.
+ *
+ * @docsCategory form-components
+ * @docsPage CheckboxInput
+ */
 export function CheckboxInput({ value, onChange, fieldDef }: Readonly<DashboardFormComponentProps>) {
     const readOnly = isReadonlyField(fieldDef);
     return <Checkbox checked={value} onCheckedChange={onChange} disabled={readOnly} />;

package/src/lib/components/data-input/datetime-input.tsx

@@ -12,6 +12,13 @@ import { cn } from '@/vdb/lib/utils.js';
 import { CalendarClock } from 'lucide-react';
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 
+/**
+ * @description
+ * A component for selecting a date and time.
+ *
+ * @docsCategory form-components
+ * @docsPage DateTimeInput
+ */
 export function DateTimeInput({ value, onChange, fieldDef }: Readonly<DashboardFormComponentProps>) {
     const readOnly = isReadonlyField(fieldDef);
     const date = value && value instanceof Date ? value.toISOString() : (value ?? '');

package/src/lib/components/data-input/money-input.tsx

@@ -11,6 +11,14 @@ export interface MoneyInputProps extends DashboardFormComponentProps {
     currency?: string;
 }
 
+/**
+ * @description
+ * A component for displaying a money value. The `currency` can be specified, but otherwise
+ * will be taken from the active channel's default currency.
+ *
+ * @docsCategory form-components
+ * @docsPage MoneyInput
+ */
 export function MoneyInput(props: Readonly<MoneyInputProps>) {
     const { value, onChange, currency, ...rest } = props;
     const { activeChannel } = useChannel();

package/src/lib/components/data-input/number-input.tsx

@@ -4,6 +4,13 @@ import { Input } from '@/vdb/components/ui/input.js';
 import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-engine-types.js';
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 
+/**
+ * @description
+ * A component for displaying a numeric value.
+ *
+ * @docsCategory form-components
+ * @docsPage NumberInput
+ */
 export function NumberInput({ fieldDef, onChange, ...fieldProps }: Readonly<DashboardFormComponentProps>) {
     const readOnly = fieldProps.disabled || isReadonlyField(fieldDef);
     const isFloat = fieldDef ? fieldDef.type === 'float' : false;

package/src/lib/components/data-input/password-input.tsx

@@ -2,6 +2,13 @@ import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-en
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 import { Input } from '../ui/input.js';
 
+/**
+ * @description
+ * A component for displaying a password input.
+ *
+ * @docsCategory form-components
+ * @docsPage PasswordInput
+ */
 export function PasswordInput(props: Readonly<DashboardFormComponentProps>) {
     const readOnly = props.disabled || isReadonlyField(props.fieldDef);
     return (

package/src/lib/components/data-input/rich-text-input.tsx

@@ -22,6 +22,13 @@ const extensions = [
     }),
 ];
 
+/**
+ * @description
+ * A component for displaying a rich text editor. Internally uses ProseMirror (rich text editor) under the hood.
+ *
+ * @docsCategory form-components
+ * @docsPage RichTextInput
+ */
 export function RichTextInput({ value, onChange, fieldDef }: Readonly<DashboardFormComponentProps>) {
     const readOnly = isReadonlyField(fieldDef);
     const isInternalUpdate = useRef(false);

package/src/lib/components/data-input/text-input.tsx

@@ -3,6 +3,13 @@ import { Input } from '@/vdb/components/ui/input.js';
 import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-types.js';
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 
+/**
+ * @description
+ * A component for displaying a text input.
+ *
+ * @docsCategory form-components
+ * @docsPage TextInput
+ */
 export const TextInput: DashboardFormComponent = ({ value, onChange, fieldDef }) => {
     const readOnly = isReadonlyField(fieldDef);
     return <Input value={value || ''} onChange={e => onChange(e.target.value)} disabled={readOnly} />;

package/src/lib/components/data-input/textarea-input.tsx

@@ -2,6 +2,13 @@ import { Textarea } from '@/vdb/components/ui/textarea.js';
 import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-engine-types.js';
 import { isReadonlyField } from '@/vdb/framework/form-engine/utils.js';
 
+/**
+ * @description
+ * A component for displaying a textarea input.
+ *
+ * @docsCategory form-components
+ * @docsPage TextareaInput
+ */
 export function TextareaInput(props: Readonly<DashboardFormComponentProps>) {
     const readOnly = props.disabled || isReadonlyField(props.fieldDef);
     return (

package/src/lib/components/data-table/data-table-view-options.tsx

@@ -16,6 +16,7 @@ import {
     DropdownMenuSeparator,
     DropdownMenuTrigger,
 } from '@/vdb/components/ui/dropdown-menu.js';
+import { ScrollArea } from '@/vdb/components/ui/scroll-area.js';
 import { usePage } from '@/vdb/hooks/use-page.js';
 import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
 import { Trans } from '@/vdb/lib/trans.js';
@@ -76,39 +77,41 @@ export function DataTableViewOptions<TData>({ table }: DataTableViewOptionsProps
 
     return (
         <div className="flex items-center gap-2">
-            <DropdownMenu>
+            <DropdownMenu modal={false}>
                 <DropdownMenuTrigger asChild>
                     <Button variant="ghost" size="sm" className="ml-auto hidden h-8 lg:flex">
                         <Settings2 />
                         <Trans>Columns</Trans>
                     </Button>
                 </DropdownMenuTrigger>
-                <DropdownMenuContent align="end">
-                    <DndContext
-                        collisionDetection={closestCenter}
-                        onDragEnd={handleDragEnd}
-                        modifiers={[restrictToVerticalAxis]}
-                    >
-                        <SortableContext
-                            items={columns.map(col => col.id)}
-                            strategy={verticalListSortingStrategy}
+                <DropdownMenuContent align="end" className="overflow-auto">
+                    <ScrollArea className="max-h-[60vh]" type="always">
+                        <DndContext
+                            collisionDetection={closestCenter}
+                            onDragEnd={handleDragEnd}
+                            modifiers={[restrictToVerticalAxis]}
                         >
-                            {columns.map(column => (
-                                <SortableItem key={column.id} id={column.id}>
-                                    <DropdownMenuCheckboxItem
-                                        className="capitalize"
-                                        checked={column.getIsVisible()}
-                                        onCheckedChange={value => column.toggleVisibility(!!value)}
-                                        onSelect={e => e.preventDefault()}
-                                    >
-                                        {column.id}
-                                    </DropdownMenuCheckboxItem>
-                                </SortableItem>
-                            ))}
-                        </SortableContext>
-                    </DndContext>
-                    <DropdownMenuSeparator />
-                    <DropdownMenuItem onClick={handleReset}>Reset</DropdownMenuItem>
+                            <SortableContext
+                                items={columns.map(col => col.id)}
+                                strategy={verticalListSortingStrategy}
+                            >
+                                {columns.map(column => (
+                                    <SortableItem key={column.id} id={column.id}>
+                                        <DropdownMenuCheckboxItem
+                                            className="capitalize"
+                                            checked={column.getIsVisible()}
+                                            onCheckedChange={value => column.toggleVisibility(!!value)}
+                                            onSelect={e => e.preventDefault()}
+                                        >
+                                            {column.id}
+                                        </DropdownMenuCheckboxItem>
+                                    </SortableItem>
+                                ))}
+                            </SortableContext>
+                        </DndContext>
+                        <DropdownMenuSeparator />
+                        <DropdownMenuItem onClick={handleReset}>Reset</DropdownMenuItem>
+                    </ScrollArea>
                 </DropdownMenuContent>
             </DropdownMenu>
         </div>

package/src/lib/components/data-table/data-table.tsx

@@ -35,6 +35,14 @@ export interface FacetedFilter {
     options?: DataTableFacetedFilterOption[];
 }
 
+/**
+ * @description
+ * Props for configuring the {@link DataTable}.
+ *
+ * @docsCategory list-views
+ * @docsPage DataTable
+ * @since 3.4.0
+ */
 interface DataTableProps<TData> {
     children?: React.ReactNode;
     columns: ColumnDef<TData, any>[];
@@ -55,6 +63,7 @@ interface DataTableProps<TData> {
     disableViewOptions?: boolean;
     bulkActions?: BulkAction[];
     /**
+     * @description
      * This property allows full control over _all_ features of TanStack Table
      * when needed.
      */
@@ -62,6 +71,17 @@ interface DataTableProps<TData> {
     onRefresh?: () => void;
 }
 
+/**
+ * @description
+ * A data table which includes sorting, filtering, pagination, bulk actions, column controls etc.
+ *
+ * This is the building block of all data tables in the Dashboard.
+ *
+ * @docsCategory list-views
+ * @docsPage DataTable
+ * @since 3.4.0
+ * @docsWeight 0
+ */
 export function DataTable<TData>({
     children,
     columns,

package/src/lib/components/data-table/types.ts

@@ -1 +1,40 @@
+import { CellContext } from '@tanstack/table-core';
+
 export type ColumnDataType = 'String' | 'Int' | 'Float' | 'DateTime' | 'Boolean' | 'ID' | 'Money';
+
+/**
+ * @description
+ * This type is used to define re-usable components that can render a table cell in a
+ * DataTable.
+ *
+ * @example
+ * ```ts
+ * import { DataTableCellComponent } from '\@vendure/dashboard';
+ *
+ * type CustomerCellData = {
+ *     customer: {
+ *         id: string;
+ *         firstName: string;
+ *         lastName: string;
+ *     } | null;
+ * };
+ *
+ * export const CustomerCell: DataTableCellComponent<CustomerCellData> = ({ row }) => {
+ *     const value = row.original.customer;
+ *     if (!value) {
+ *         return null;
+ *     }
+ *     return (
+ *         <Button asChild variant="ghost">
+ *             <Link to={`/customers/${value.id}`}>
+ *                 {value.firstName} {value.lastName}
+ *             </Link>
+ *         </Button>
+ *     );
+ * };
+ * ```
+ *
+ * @docsCategory list-views
+ * @since 3.4.0
+ */
+export type DataTableCellComponent<T> = <Data extends T>(context: CellContext<Data, any>) => any;

package/src/lib/components/layout/channel-switcher.tsx

@@ -54,9 +54,7 @@ export function ChannelSwitcher() {
         setContentLanguage,
     } = useUserSettings();
     const [showManageLanguagesDialog, setShowManageLanguagesDialog] = useState(false);
-
-    // Use the selected channel if available, otherwise fall back to the active channel
-    const displayChannel = activeChannel || activeChannel;
+    const displayChannel = activeChannel;
 
     // Get available languages from server config
     const availableLanguages = serverConfig?.availableLanguages || [];

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>,