@vendure/dashboard 3.4.2-master-202509090229 → 3.4.2

package/src/lib/components/shared/paginated-list-data-table.tsx

@@ -1,22 +1,15 @@
-import { DataTable, FacetedFilter } from '@/vdb/components/data-table/data-table.js';
-import {
-    getObjectPathToPaginatedList
-} from '@/vdb/framework/document-introspection/get-document-structure.js';
-import { useListQueryFields } from '@/vdb/framework/document-introspection/hooks.js';
-import { api } from '@/vdb/graphql/api.js';
+import { DataTable, FacetedFilter } from '\@/vdb/components/data-table/data-table.js';
+import { getObjectPathToPaginatedList } from '\@/vdb/framework/document-introspection/get-document-structure.js';
+import { useListQueryFields } from '\@/vdb/framework/document-introspection/hooks.js';
+import { api } from '\@/vdb/graphql/api.js';
 import { keepPreviousData, useQuery, useQueryClient } from '@tanstack/react-query';
 import { useDebounce } from '@uidotdev/usehooks';
 
-import { BulkAction } from '@/vdb/framework/extension-api/types/index.js';
-import { ResultOf } from '@/vdb/graphql/graphql.js';
-import { useExtendedListQuery } from '@/vdb/hooks/use-extended-list-query.js';
+import { BulkAction } from '\@/vdb/framework/extension-api/types/index.js';
+import { ResultOf } from '\@/vdb/graphql/graphql.js';
+import { useExtendedListQuery } from '\@/vdb/hooks/use-extended-list-query.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
-import {
-    ColumnFiltersState,
-    ColumnSort,
-    SortingState,
-    Table
-} from '@tanstack/react-table';
+import { ColumnFiltersState, ColumnSort, SortingState, Table } from '@tanstack/react-table';
 import { ColumnDef, Row, TableOptions, VisibilityState } from '@tanstack/table-core';
 import React from 'react';
 import { getColumnVisibility } from '../data-table/data-table-utils.js';
@@ -163,6 +156,8 @@ export const PaginatedListContext = React.createContext<PaginatedListContext | u
  *     },
  * });
  * ```
+ * @docsCategory hooks
+ * @since 3.4.0
  */
 export function usePaginatedList() {
     const context = React.useContext(PaginatedListContext);
@@ -179,6 +174,14 @@ export interface RowAction<T> {
 
 export type PaginatedListRefresherRegisterFn = (refreshFn: () => void) => void;
 
+/**
+ * @description
+ * Props to configure the {@link PaginatedListDataTable} component.
+ *
+ * @docsCategory list-views
+ * @docsPage PaginatedListDataTable
+ * @since 3.4.0
+ */
 export interface PaginatedListDataTableProps<
     T extends TypedDocumentNode<U, V>,
     U extends ListQueryShape,
@@ -218,6 +221,116 @@ export interface PaginatedListDataTableProps<
 
 export const PaginatedListDataTableKey = 'PaginatedListDataTable';
 
+/**
+ * @description
+ * A wrapper around the {@link DataTable} component, which automatically configures functionality common to
+ * list queries that implement the `PaginatedList` interface, which is the common way of representing lists
+ * of data in Vendure.
+ *
+ * Given a GraphQL query document node, the component will automatically configure the required columns
+ * with sorting & filtering functionality.
+ *
+ * The automatic features can be further customized and enhanced using the many options available in the props.
+ *
+ * @example
+ * ```tsx
+ * import { Money } from '\@/vdb/components/data-display/money.js';
+ * import { PaginatedListDataTable } from '\@/vdb/components/shared/paginated-list-data-table.js';
+ * import { Badge } from '\@/vdb/components/ui/badge.js';
+ * import { Button } from '\@/vdb/components/ui/button.js';
+ * import { Link } from '\@tanstack/react-router';
+ * import { ColumnFiltersState, SortingState } from '\@tanstack/react-table';
+ * import { useState } from 'react';
+ * import { customerOrderListDocument } from '../customers.graphql.js';
+ *
+ * interface CustomerOrderTableProps {
+ *     customerId: string;
+ * }
+ *
+ * export function CustomerOrderTable({ customerId }: Readonly<CustomerOrderTableProps>) {
+ *     const [page, setPage] = useState(1);
+ *     const [pageSize, setPageSize] = useState(10);
+ *     const [sorting, setSorting] = useState<SortingState>([{ id: 'orderPlacedAt', desc: true }]);
+ *     const [filters, setFilters] = useState<ColumnFiltersState>([]);
+ *
+ *     return (
+ *         <PaginatedListDataTable
+ *             listQuery={customerOrderListDocument}
+ *             transformVariables={variables => {
+ *                 return {
+ *                     ...variables,
+ *                     customerId,
+ *                 };
+ *             }}
+ *             defaultVisibility={{
+ *                 id: false,
+ *                 createdAt: false,
+ *                 updatedAt: false,
+ *                 type: false,
+ *                 currencyCode: false,
+ *                 total: false,
+ *             }}
+ *             customizeColumns={{
+ *                 total: {
+ *                     header: 'Total',
+ *                     cell: ({ cell, row }) => {
+ *                         const value = cell.getValue();
+ *                         const currencyCode = row.original.currencyCode;
+ *                         return <Money value={value} currency={currencyCode} />;
+ *                     },
+ *                 },
+ *                 totalWithTax: {
+ *                     header: 'Total with Tax',
+ *                     cell: ({ cell, row }) => {
+ *                         const value = cell.getValue();
+ *                         const currencyCode = row.original.currencyCode;
+ *                         return <Money value={value} currency={currencyCode} />;
+ *                     },
+ *                 },
+ *                 state: {
+ *                     header: 'State',
+ *                     cell: ({ cell }) => {
+ *                         const value = cell.getValue() as string;
+ *                         return <Badge variant="outline">{value}</Badge>;
+ *                     },
+ *                 },
+ *                 code: {
+ *                     header: 'Code',
+ *                     cell: ({ cell, row }) => {
+ *                         const value = cell.getValue() as string;
+ *                         const id = row.original.id;
+ *                         return (
+ *                             <Button asChild variant="ghost">
+ *                                 <Link to={`/orders/${id}`}>{value}</Link>
+ *                             </Button>
+ *                         );
+ *                     },
+ *                 },
+ *             }}
+ *             page={page}
+ *             itemsPerPage={pageSize}
+ *             sorting={sorting}
+ *             columnFilters={filters}
+ *             onPageChange={(_, page, perPage) => {
+ *                 setPage(page);
+ *                 setPageSize(perPage);
+ *             }}
+ *             onSortChange={(_, sorting) => {
+ *                 setSorting(sorting);
+ *             }}
+ *             onFilterChange={(_, filters) => {
+ *                 setFilters(filters);
+ *             }}
+ *         />
+ *     );
+ * }
+ * ```
+ *
+ * @docsCategory list-views
+ * @docsPage PaginatedListDataTable
+ * @since 3.4.0
+ * @docsWeight 0
+ */
 export function PaginatedListDataTable<
     T extends TypedDocumentNode<U, V>,
     U extends Record<string, any> = any,
@@ -358,4 +471,3 @@ export function PaginatedListDataTable<
         </PaginatedListContext.Provider>
     );
 }
-

package/src/lib/components/shared/permission-guard.tsx

@@ -1,8 +1,24 @@
 import { usePermissions } from '@/vdb/hooks/use-permissions.js';
 import { Permission } from '@vendure/common/lib/generated-types';
 
+/**
+ * @description
+ * The props for the PermissionGuard component.
+ *
+ * @docsCategory components
+ * @docsPage PermissionGuard
+ * @since 3.4.0
+ */
 export interface PermissionGuardProps {
+    /**
+     * @description
+     * The permission(s) required to access the children.
+     */
     requires: Permission | string | string[] | Permission[];
+    /**
+     * @description
+     * The children to render if the user has the required permissions.
+     */
     children: React.ReactNode;
 }
 
@@ -10,6 +26,20 @@ export interface PermissionGuardProps {
  * @description
  * This component is used to protect a route from unauthorized access.
  * It will render the children if the user has the required permissions.
+ * 
+ * @example
+ * ```tsx
+ * <PermissionGuard requires={['UpdateTaxCategory']}>
+ *     <Button type="submit">
+ *         <Trans>Update</Trans>
+ *     </Button>
+ * </PermissionGuard>
+ * ```
+ * 
+ * @docsCategory components
+ * @docsPage PermissionGuard
+ * @docsWeight 0
+ * @since 3.4.0
  */
 export function PermissionGuard({ requires, children }: Readonly<PermissionGuardProps>) {
     const { hasPermissions } = usePermissions();

package/src/lib/components/shared/table-cell/order-table-cell-components.tsx

@@ -1,5 +1,5 @@
 import { Money } from '@/vdb/components/data-display/money.js';
-import { DataTableCellComponent } from '@/vdb/components/shared/table-cell/table-cell-types.js';
+import { DataTableCellComponent } from '@/vdb/components/data-table/types.js';
 import { Badge } from '@/vdb/components/ui/badge.js';
 import { Button } from '@/vdb/components/ui/button.js';
 import { Link } from '@tanstack/react-router';

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

@@ -11,11 +11,27 @@ export type TranslatableEntity = FieldValues & {
     translations?: Array<{ languageCode: string }> | null;
 };
 
+/**
+ * @description
+ * The props for the TranslatableFormField component.
+ *
+ * @docsCategory form-components
+ * @docsPage TranslatableFormFieldWrapper
+ * @since 3.4.0
+ */
 export type TranslatableFormFieldProps<TFieldValues extends TranslatableEntity | TranslatableEntity[]> = Omit<
     ControllerProps<TFieldValues>,
     'name'
 > & {
+    /**
+     * @description
+     * The label for the form field.
+     */
     label?: React.ReactNode;
+    /**
+     * @description
+     * The name of the form field.
+     */
     name: TFieldValues extends TranslatableEntity
         ? keyof Omit<NonNullable<TFieldValues['translations']>[number], 'languageCode'>
         : TFieldValues extends TranslatableEntity[]
@@ -57,6 +73,42 @@ export type TranslatableFormFieldWrapperProps<
 > = TranslatableFormFieldProps<TFieldValues> &
     Omit<React.ComponentProps<typeof FormFieldWrapper<TFieldValues>>, 'name'>;
 
+/**
+ * @description
+ * This is the equivalent of the {@link FormFieldWrapper} component, but for translatable fields.
+ * 
+ * @example
+ * ```tsx
+ * <PageBlock column="main" blockId="main-form">
+ *     <DetailFormGrid>
+ *         <TranslatableFormFieldWrapper
+ *             control={form.control}
+ *             name="name"
+ *             label={<Trans>Product name</Trans>}
+ *             render={({ field }) => <Input {...field} />}
+ *         />
+ *         <TranslatableFormFieldWrapper
+ *             control={form.control}
+ *             name="slug"
+ *             label={<Trans>Slug</Trans>}
+ *             render={({ field }) => <Input {...field} />}
+ *         />
+ *     </DetailFormGrid>
+
+ *     <TranslatableFormFieldWrapper
+ *         control={form.control}
+ *         name="description"
+ *         label={<Trans>Description</Trans>}
+ *         render={({ field }) => <RichTextInput {...field} />}
+ *     />
+ * </PageBlock>
+ * ```
+ *
+ * @docsCategory form-components
+ * @docsPage TranslatableFormFieldWrapper
+ * @docsWeight 0
+ * @since 3.4.0
+ */
 export const TranslatableFormFieldWrapper = <
     TFieldValues extends TranslatableEntity | TranslatableEntity[] = TranslatableEntity,
 >({

package/src/lib/components/shared/vendure-image.tsx

@@ -2,6 +2,14 @@ import { cn } from '@/vdb/lib/utils.js';
 import { Image } from 'lucide-react';
 import React from 'react';
 
+/**
+ * @description
+ * The type of object that can be used as an asset in the {@link VendureImage} component.
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @since 3.4.0
+ */
 export interface AssetLike {
     id: string;
     preview: string; // Base URL of the asset
@@ -9,23 +17,127 @@ export interface AssetLike {
     focalPoint?: { x: number; y: number } | null;
 }
 
+/**
+ * @description
+ * The presets that can be used for the {@link VendureImage} component.
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @since 3.4.0
+ */
 export type ImagePreset = 'tiny' | 'thumb' | 'small' | 'medium' | 'large' | null;
+
+/**
+ * @description
+ * The formats that can be used for the {@link VendureImage} component.
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @since 3.4.0
+ */
 export type ImageFormat = 'jpg' | 'jpeg' | 'png' | 'webp' | 'avif' | null;
+
+/**
+ * @description
+ * The modes that can be used for the {@link VendureImage} component.
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @since 3.4.0
+ */
 export type ImageMode = 'crop' | 'resize' | null;
 
+/**
+ * @description
+ * The props for the {@link VendureImage} component.
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @docsWeight 1
+ * @since 3.4.0
+ */
 export interface VendureImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+    /**
+     * @description
+     * The asset to display.
+     */
     asset: AssetLike | null | undefined;
+    /**
+     * @description
+     * The preset to use for the image.
+     */
     preset?: ImagePreset;
+    /**
+     * @description
+     * The crop/resize mode to use for the image.
+     */
     mode?: ImageMode;
+    /**
+     * @description
+     * The width of the image.
+     */
     width?: number;
+    /**
+     * @description
+     * The height of the image.
+     */
     height?: number;
+    /**
+     * @description
+     * The format of the image.
+     */
     format?: ImageFormat;
+    /**
+     * @description
+     * The quality of the image.
+     */
     quality?: number;
-    useFocalPoint?: boolean; // Whether to use the asset's focal point in crop mode
-    fallback?: React.ReactNode; // What to show if no asset is provided
+    /**
+     * @description
+     * Whether to use the asset's focal point in crop mode.
+     */
+    useFocalPoint?: boolean;
+    /**
+     * @description
+     * The fallback to show if no asset is provided. If no fallback is provided, 
+     * a default placeholder will be shown.
+     */ 
+    fallback?: React.ReactNode;
+    /**
+     * @description
+     * The ref to the image element.
+     */
     ref?: React.Ref<HTMLImageElement>;
 }
 
+/**
+ * @description
+ * A component for displaying an image from a Vendure asset.
+ * 
+ * Supports the following features:
+ * 
+ * * Presets
+ * * Cropping
+ * * Resizing
+ * * Formatting
+ * * Quality
+ * * Focal point
+ * * Fallback
+ * 
+ * @example
+ * ```tsx
+ *  <VendureImage
+ *      asset={asset}
+ *      preset="thumb"
+ *      className="w-full h-full object-contain"
+ *  />
+ * ```
+ *
+ * @docsCategory components
+ * @docsPage VendureImage
+ * @docsWeight 0
+ * @since 3.4.0
+ */
 export function VendureImage({
     asset,
     preset = null,

package/src/lib/framework/extension-api/define-dashboard-extension.ts

@@ -27,12 +27,34 @@ export function executeDashboardExtensionCallbacks() {
 
 /**
  * @description
- * **Status: Developer Preview**
+ * The main entry point for extensions to the React-based dashboard. Every dashboard extension
+ * must contain a call to this function, usually in the entry point file that is referenced by
+ * the `dashboard` property of the plugin decorator.
  *
- * The main entry point for extensions to the React-based dashboard.
+ * Every type of customisation of the dashboard can be defined here, including:
  *
+ * - Navigation (nav sections and routes)
+ * - Layout (action bar items and page blocks)
+ * - Widgets
+ * - Form components (custom form components, input components, and display components)
+ * - Data tables
+ * - Detail forms
+ * - Login
  *
- * @docsCategory extensions
+ * @example
+ * ```tsx
+ * defineDashboardExtension({
+ *  navSections: [],
+ *  routes: [],
+ *  pageBlocks: [],
+ *  actionBarItems: [],
+ * });
+ * ```
+ *
+ *
+ * @docsCategory extensions-api
+ * @docsPage defineDashboardExtension
+ * @docsWeight 0
  * @since 3.3.0
  */
 export function defineDashboardExtension(extension: DashboardExtension) {

package/src/lib/framework/extension-api/extension-api-types.ts

@@ -14,11 +14,20 @@ import {
 
 /**
  * @description
- * **Status: Developer Preview**
+ * This is the main interface for defining _all_ extensions to the dashboard.
  *
- * This is used to define the routes, widgets, etc. that will be displayed in the dashboard.
+ * Every type of customisation of the dashboard can be defined here, including:
  *
- * @docsCategory extensions
+ * - Navigation (nav sections and routes)
+ * - Layout (action bar items and page blocks)
+ * - Widgets for the Insights page
+ * - Form components
+ * - Data tables
+ * - Detail forms
+ * - Login page customisation
+ *
+ * @docsCategory extensions-api
+ * @docsPage defineDashboardExtension
  * @since 3.3.0
  */
 export interface DashboardExtension {

package/src/lib/framework/extension-api/types/alerts.ts

@@ -1,10 +1,9 @@
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Allows you to define custom alerts that can be displayed in the dashboard.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
+ * @docsPage Alerts
  * @since 3.3.0
  */
 export interface DashboardAlertDefinition<TResponse = any> {

package/src/lib/framework/extension-api/types/data-table.ts

@@ -6,7 +6,7 @@ import { DocumentNode } from 'graphql';
  * Allows you to define custom display components for specific columns in data tables.
  * The pageId is already defined in the data table extension, so only the column name is needed.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage DataTable
  * @since 3.4.0
  */
@@ -61,7 +61,7 @@ export type BulkAction = {
  * @description
  * This allows you to customize aspects of existing data tables in the dashboard.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage DataTable
  * @since 3.4.0
  */

package/src/lib/framework/extension-api/types/detail-forms.ts

@@ -6,7 +6,7 @@ import { DocumentNode } from 'graphql';
  * Allows you to define custom input components for specific fields in detail forms.
  * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage DetailForms
  * @since 3.4.0
  */
@@ -36,7 +36,7 @@ export interface DashboardDetailFormInputComponent {
  *
  * @since 3.4.0
  * @docsPage DetailForms
- * @docsCategory extensions
+ * @docsCategory extensions-api
  */
 export interface DashboardDetailFormExtensionDefinition {
     /**

package/src/lib/framework/extension-api/types/form-components.ts

@@ -4,7 +4,7 @@ import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-
  * @description
  * Allows you to define custom form components for custom fields in the dashboard.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage FormComponents
  * @since 3.4.0
  */
@@ -27,7 +27,7 @@ export interface DashboardCustomFormComponent {
  * Interface for registering custom field components in the dashboard.
  * For input and display components, use the co-located approach with detailForms.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage FormComponents
  * @since 3.4.0
  */

package/src/lib/framework/extension-api/types/layout.ts

@@ -2,17 +2,16 @@ import type React from 'react';
 
 import { PageContextValue } from '../../layout-engine/page-provider.js';
 
-export interface ActionBarButtonState {
-    disabled: boolean;
-    visible: boolean;
-}
-
 /**
  * @description
- * Allows you to define custom action bar items for any page in the dashboard.
+ * Allows you to define custom action bar items for any page in the dashboard, which is the
+ * top bar that normally contains the main call-to-action buttons such as "update" or "create".
  *
- * @docsCategory extensions
- * @docsPage Layout
+ * This API also allows you to specify dropdown menu items, which when defined, will appear in
+ * a context menu to the very right of the ActionBar.
+ *
+ * @docsCategory extensions-api
+ * @docsPage ActionBar
  * @since 3.3.0
  */
 export interface DashboardActionBarItem {
@@ -23,7 +22,8 @@ export interface DashboardActionBarItem {
     pageId: string;
     /**
      * @description
-     * A React component that will be rendered in the action bar.
+     * A React component that will be rendered in the action bar. Typically, you would use
+     * the default Shadcn `<Button>` component.
      */
     component: React.FunctionComponent<{ context: PageContextValue }>;
     /**
@@ -54,6 +54,16 @@ export interface DashboardActionBarItem {
     requiresPermission?: string | string[];
 }
 
+/**
+ * @description
+ * The relative position of a PageBlock. This is determined by finding an existing
+ * block, and then specifying whether your custom block should come before, after,
+ * or completely replace that block.
+ *
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
+ * @since 3.3.0
+ */
 export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | 'replace' };
 
 /**
@@ -62,8 +72,8 @@ export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | '
  * "developer mode" in the dashboard user menu (bottom left corner) and then
  * clicking the `< />` icon when hovering over a page block.
  *
- * @docsCategory extensions
- * @docsPage Layout
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
  * @since 3.3.0
  */
 export type PageBlockLocation = {
@@ -77,8 +87,9 @@ export type PageBlockLocation = {
  * This allows you to insert a custom component into a specific location
  * on any page in the dashboard.
  *
- * @docsCategory extensions
- * @docsPage Layout
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
+ * @docsWeight 0
  * @since 3.3.0
  */
 export interface DashboardPageBlockDefinition {