@vendure/dashboard 3.4.2-master-202509090229 → 3.4.2

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

@@ -4,7 +4,7 @@ import type React from 'react';
  * @description
  * Defines a custom logo component for the login page.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Login
  * @since 3.4.0
  */
@@ -20,7 +20,7 @@ export interface LoginLogoExtension {
  * @description
  * Defines content to display before the login form.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Login
  * @since 3.4.0
  */
@@ -36,7 +36,7 @@ export interface LoginBeforeFormExtension {
  * @description
  * Defines content to display after the login form.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Login
  * @since 3.4.0
  */
@@ -52,7 +52,7 @@ export interface LoginAfterFormExtension {
  * @description
  * Defines a custom login image component that replaces the default image panel.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Login
  * @since 3.4.0
  */
@@ -68,8 +68,9 @@ export interface LoginImageExtension {
  * @description
  * Defines all available login page extensions.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Login
+ * @docsWeight 0
  * @since 3.4.0
  */
 export interface DashboardLoginExtensions {

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

@@ -8,8 +8,8 @@ import { NavMenuItem } from '../../nav-menu/nav-menu-extensions.js';
  * @description
  * Defines a custom route for the dashboard with optional navigation menu integration.
  *
- * @docsCategory extensions
- * @docsPage Navigation
+ * @docsCategory extensions-api
+ * @docsPage Routes
  * @since 3.4.0
  */
 export interface DashboardRouteDefinition {
@@ -42,7 +42,7 @@ export interface DashboardRouteDefinition {
  * @description
  * Defines a custom navigation section in the dashboard sidebar.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
  * @docsPage Navigation
  * @since 3.4.0
  */

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

@@ -4,7 +4,8 @@ import React, { PropsWithChildren } from 'react';
  * @description
  * Base props interface for dashboard widgets.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
+ * @docsPage widgets
  * @since 3.3.0
  */
 export type DashboardBaseWidgetProps = PropsWithChildren<{
@@ -19,7 +20,8 @@ export type DashboardBaseWidgetProps = PropsWithChildren<{
  * @description
  * Represents an instance of a dashboard widget with its layout and configuration.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
+ * @docsPage widgets
  * @since 3.3.0
  */
 export type DashboardWidgetInstance = {
@@ -60,7 +62,9 @@ export type DashboardWidgetInstance = {
  *
  * Defines a dashboard widget that can be added to the dashboard.
  *
- * @docsCategory extensions
+ * @docsCategory extensions-api
+ * @docsPage Widgets
+ * @docsWeight 0
  * @since 3.3.0
  */
 export type DashboardWidgetDefinition = {

package/src/lib/framework/form-engine/form-engine-types.ts

@@ -85,8 +85,9 @@ export type DateTimeStructField = Extract<StructField, { type: 'datetime' }>;
  * }
  * ```
  *
- * @docsCategory forms
- * @docsPage DashboardFormComponent
+ * @docsCategory extensions-api
+ * @docsPage FormComponents
+ * @since 3.4.0
  */
 export type DashboardFormComponentProps<
     TFieldValues extends FieldValues = FieldValues,
@@ -116,8 +117,9 @@ export type DashboardFormComponentProps<
  * // highlight-end
  * ```
  *
- * @docsCategory forms
- * @docsPage DashboardFormComponent
+ * @docsCategory extensions-api
+ * @docsPage FormComponents
+ * @since 3.4.0
  */
 export type DashboardFormComponentMetadata = {
     /**
@@ -127,6 +129,10 @@ export type DashboardFormComponentMetadata = {
      * handle both lists and single values.
      */
     isListInput?: boolean | 'dynamic';
+    /**
+     * @description
+     * TODO: not currently implemented
+     */
     isFullWidth?: boolean;
 };
 
@@ -154,9 +160,9 @@ export type DashboardFormComponentMetadata = {
  * };
  * ```
  *
- * @docsCategory forms
- * @docsPage DashboardFormComponent
- * @docsWeight 0
+ * @docsCategory extensions-api
+ * @docsPage FormComponents
+ * @since 3.4.0
  */
 export type DashboardFormComponent = React.ComponentType<DashboardFormComponentProps> & {
     metadata?: DashboardFormComponentMetadata;

package/src/lib/framework/form-engine/use-generated-form.tsx

@@ -9,13 +9,33 @@ import { getOperationVariablesFields } from '../document-introspection/get-docum
 import { createFormSchemaFromFields, getDefaultValuesFromFields } from './form-schema-tools.js';
 import { removeEmptyIdFields, transformRelationFields } from './utils.js';
 
+/**
+ * @description
+ * Options for the useGeneratedForm hook.
+ *
+ * @docsCategory detail-views
+ * @docsPage useGeneratedForm
+ * @since 3.3.0
+ */
 export interface GeneratedFormOptions<
     T extends TypedDocumentNode<any, any>,
     VarName extends keyof VariablesOf<T> | undefined = 'input',
     E extends Record<string, any> = Record<string, any>,
 > {
+    /**
+     * @description
+     * The document to use to generate the form.
+     */
     document?: T;
+    /**
+     * @description
+     * The name of the variable to use in the document.
+     */
     varName?: VarName;
+    /**
+     * @description
+     * The entity to use to generate the form.
+     */
     entity: E | null | undefined;
     customFieldConfig?: any[]; // Add custom field config for validation
     setValues: (
@@ -32,6 +52,30 @@ export interface GeneratedFormOptions<
  * It will create a form with the fields defined in the document's input type.
  * It will also create a submit handler that will submit the form to the server.
  *
+ * This hook is mostly used internally by the higher-level {@link useDetailPage} hook,
+ * but can in some cases be useful to use directly.
+ *
+ * @example
+ * ```tsx
+ * const { form, submitHandler } = useGeneratedForm({
+ *  document: setDraftOrderCustomFieldsDocument,
+ *  varName: undefined,
+ *  entity: entity,
+ *  setValues: entity => {
+ *    return {
+ *      orderId: entity.id,
+ *      input: {
+ *        customFields: entity.customFields,
+ *      },
+ *    };
+ *  },
+ * });
+ * ```
+ *
+ * @docsCategory detail-views
+ * @docsPage useGeneratedForm
+ * @since 3.3.0
+ * @docsWeight 0
  */
 export function useGeneratedForm<
     T extends TypedDocumentNode<any, any>,

package/src/lib/framework/layout-engine/page-layout.tsx

@@ -20,8 +20,21 @@ import { PageContext, PageContextValue } from '@/vdb/framework/layout-engine/pag
 import { getDashboardActionBarItems, getDashboardPageBlocks } from './layout-extensions.js';
 import { LocationWrapper } from './location-wrapper.js';
 
+/**
+ * @description
+ * The props used to configure the {@link Page} component.
+ *
+ * @docsCategory page-layout
+ * @docsPage Page
+ * @since 3.3.0
+ */
 export interface PageProps extends ComponentProps<'div'> {
+    /**
+     * @description
+     * A string identifier for the page, e.g. "product-list", "review-detail", etc.
+     */
     pageId?: string;
+
     entity?: any;
     form?: UseFormReturn<any>;
     submitHandler?: any;
@@ -29,8 +42,6 @@ export interface PageProps extends ComponentProps<'div'> {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * This component should be used to wrap _all_ pages in the dashboard. It provides
  * a consistent layout as well as a context for the slot-based PageBlock system.
  *
@@ -39,8 +50,33 @@ export interface PageProps extends ComponentProps<'div'> {
  *  - {@link PageTitle}
  *  - {@link PageActionBar}
  *  - {@link PageLayout}
+ * 
+ * @example
+ * ```tsx
+ * import { Page, PageTitle, PageActionBar, PageLayout, PageBlock, Button } from '\@vendure/dashboard';
+ * 
+ * const pageId = 'my-page';
+ * 
+ * export function MyPage() {
+ *  return (
+ *    <Page pageId={pageId} form={form} submitHandler={submitHandler} entity={entity}>
+ *      <PageTitle>My Page</PageTitle>
+ *      <PageActionBar>
+ *        <PageActionBarRight>
+ *          <Button>Save</Button>
+ *        </PageActionBarRight>
+ *      </PageActionBar>
+ *      <PageLayout>
+ *        <PageBlock column="main" blockId="my-block">
+ *          <div>My Block</div>
+ *        </PageBlock>
+ *      </PageLayout>
+ *    </Page>
+ *  )
+ * }
+ * ```
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage Page
  * @docsWeight 0
  * @since 3.3.0
@@ -133,7 +169,7 @@ export function PageContentWithOptionalForm({
  * @description
  * **Status: Developer Preview**
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageLayout
  * @since 3.3.0
  */
@@ -156,13 +192,11 @@ function isPageBlock(child: unknown): child is React.ReactElement<PageBlockProps
 }
 
 /**
- * @description
- * **Status: Developer Preview**
- *
+ * @description *
  * This component governs the layout of the contents of a {@link Page} component.
  * It should contain all the {@link PageBlock} components that are to be displayed on the page.
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageLayout
  * @docsWeight 0
  * @since 3.3.0
@@ -247,11 +281,9 @@ export function DetailFormGrid({ children }: Readonly<{ children: React.ReactNod
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * A component for displaying the title of a page. This should be used inside the {@link Page} component.
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageTitle
  * @since 3.3.0
  */
@@ -260,14 +292,12 @@ export function PageTitle({ children }: Readonly<{ children: React.ReactNode }>)
 }
 
 /**
- * @description
- * **Status: Developer Preview**
- *
+ * @description *
  * A component for displaying the main actions for a page. This should be used inside the {@link Page} component.
  * It should be used in conjunction with the {@link PageActionBarLeft} and {@link PageActionBarRight} components
  * as direct children.
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageActionBar
  * @docsWeight 0
  * @since 3.3.0
@@ -288,9 +318,9 @@ export function PageActionBar({ children }: Readonly<{ children: React.ReactNode
 
 /**
  * @description
- * **Status: Developer Preview**
- *
- * @docsCategory components
+ * The PageActionBarLeft component should be used to display the left content of the action bar.
+ * 
+ * @docsCategory page-layout
  * @docsPage PageActionBar
  * @since 3.3.0
  */
@@ -302,9 +332,9 @@ type InlineDropdownItem = Omit<DashboardActionBarItem, 'type' | 'pageId'>;
 
 /**
  * @description
- * **Status: Developer Preview**
+ * The PageActionBarRight component should be used to display the right content of the action bar.
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageActionBar
  * @since 3.3.0
  */
@@ -375,31 +405,59 @@ function PageActionBarDropdown({
 
 /**
  * @description
- * **Status: Developer Preview**
+ * Props used to configure the {@link PageBlock} component.
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageBlock
  * @since 3.3.0
  */
 export type PageBlockProps = {
+    /**
+     * @description
+     * The content of the block.
+     */
     children?: React.ReactNode;
-    /** Which column this block should appear in */
+    /**
+     * @description
+     * Which column this block should appear in
+     */
     column: 'main' | 'side';
+    /**
+     * @description
+     * The ID of the block, e.g. "gift-cards" or "related-products".
+     */
     blockId?: string;
+    /**
+     * @description
+     * The title of the block, e.g. "Gift Cards" or "Related Products".
+     */
     title?: React.ReactNode | string;
+    /**
+     * @description
+     * An optional description of the block.
+     */
     description?: React.ReactNode | string;
+    /**
+     * @description
+     * An optional set of CSS classes to apply to the block.
+     */
     className?: string;
 };
 
 /**
- * @description
- * **Status: Developer Preview**
- *
+ * @description *
  * A component for displaying a block of content on a page. This should be used inside the {@link PageLayout} component.
  * It should be provided with a `column` prop to determine which column it should appear in, and a `blockId` prop
  * to identify the block.
+ * 
+ * @example
+ * ```tsx
+ * <PageBlock column="main" blockId="my-block">
+ *  <div>My Block</div>
+ * </PageBlock>
+ * ```
  *
- * @docsCategory components
+ * @docsCategory page-layout
  * @docsPage PageBlock
  * @docsWeight 0
  * @since 3.3.0
@@ -465,12 +523,17 @@ export function FullWidthPageBlock({
 }
 
 /**
- * @description
- * **Status: Developer Preview**
- *
+ * @description *
  * A component for displaying an auto-generated form for custom fields on a page.
+ * This is a special form of {@link PageBlock} that automatically generates
+ * a form corresponding to the custom fields for the given entity type.
  *
- * @docsCategory components
+ * @example
+ * ```tsx
+ * <CustomFieldsPageBlock column="main" entityType="Product" control={form.control} />
+ * ```
+ *
+ * @docsCategory page-layout
  * @docsPage PageBlock
  * @since 3.3.0
  */

package/src/lib/framework/page/detail-page.tsx

@@ -33,9 +33,9 @@ import { DetailEntityPath } from './page-types.js';
 
 /**
  * @description
- * **Status: Developer Preview**
+ * Props to configure the {@link DetailPage} component.
  *
- * @docsCategory components
+ * @docsCategory detail-views
  * @docsPage DetailPage
  * @since 3.3.0
  */
@@ -138,13 +138,11 @@ function FieldInputRenderer<
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Auto-generates a detail page with a form based on the provided query and mutation documents.
  *
  * For more control over the layout, you would use the more low-level {@link Page} component.
  *
- * @docsCategory components
+ * @docsCategory detail-views
  * @docsPage DetailPage
  * @docsWeight 0
  * @since 3.3.0

package/src/lib/framework/page/list-page.tsx

@@ -22,9 +22,9 @@ import { FullWidthPageBlock, Page, PageActionBar, PageLayout, PageTitle } from '
 
 /**
  * @description
- * **Status: Developer Preview**
+ * Props to configure the {@link ListPage} component.
  *
- * @docsCategory components
+ * @docsCategory list-views
  * @docsPage ListPage
  * @since 3.3.0
  */
@@ -55,6 +55,7 @@ export interface ListPageProps<
     setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;
     bulkActions?: BulkAction[];
     /**
+     * @description
      * Register a function that allows you to assign a refresh function for
      * this list. The function can be assigned to a ref and then called when
      * the list needs to be refreshed.
@@ -64,11 +65,92 @@ export interface ListPageProps<
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Auto-generates a list page with columns generated based on the provided query document fields.
  *
- * @docsCategory components
+ * @example
+ * ```tsx
+ * import {
+ *     Button,
+ *     DashboardRouteDefinition,
+ *     ListPage,
+ *     PageActionBarRight,
+ *     DetailPageButton,
+ * } from '@vendure/dashboard';
+ * import { Link } from '@tanstack/react-router';
+ * import { PlusIcon } from 'lucide-react';
+ *
+ * // This function is generated for you by the `vendureDashboardPlugin` in your Vite config.
+ * // It uses gql-tada to generate TypeScript types which give you type safety as you write
+ * // your queries and mutations.
+ * import { graphql } from '@/gql';
+ *
+ * // The fields you select here will be automatically used to generate the appropriate columns in the
+ * // data table below.
+ * const getArticleList = graphql(`
+ *     query GetArticles($options: ArticleListOptions) {
+ *         articles(options: $options) {
+ *             items {
+ *                 id
+ *                 createdAt
+ *                 updatedAt
+ *                 isPublished
+ *                 title
+ *                 slug
+ *                 body
+ *                 customFields
+ *             }
+ *         }
+ *     }
+ * `);
+ *
+ * const deleteArticleDocument = graphql(`
+ *     mutation DeleteArticle($id: ID!) {
+ *         deleteArticle(id: $id) {
+ *             result
+ *         }
+ *     }
+ * `);
+ *
+ * export const articleList: DashboardRouteDefinition = {
+ *     navMenuItem: {
+ *         sectionId: 'catalog',
+ *         id: 'articles',
+ *         url: '/articles',
+ *         title: 'CMS Articles',
+ *     },
+ *     path: '/articles',
+ *     loader: () => ({
+ *         breadcrumb: 'Articles',
+ *     }),
+ *     component: route => (
+ *         <ListPage
+ *             pageId="article-list"
+ *             title="Articles"
+ *             listQuery={getArticleList}
+ *             deleteMutation={deleteArticleDocument}
+ *             route={route}
+ *             customizeColumns={{
+ *                 title: {
+ *                     cell: ({ row }) => {
+ *                         const post = row.original;
+ *                         return <DetailPageButton id={post.id} label={post.title} />;
+ *                     },
+ *                 },
+ *             }}
+ *         >
+ *             <PageActionBarRight>
+ *                 <Button asChild>
+ *                     <Link to="./new">
+ *                         <PlusIcon className="mr-2 h-4 w-4" />
+ *                         New article
+ *                     </Link>
+ *                 </Button>
+ *             </PageActionBarRight>
+ *         </ListPage>
+ *     ),
+ * };
+ * ```
+ * @docsCategory list-views
  * @docsPage ListPage
  * @docsWeight 0
  * @since 3.3.0

package/src/lib/framework/page/use-detail-page.ts

@@ -37,9 +37,9 @@ const NEW_ENTITY_ID = '__NEW__';
 
 /**
  * @description
- * **Status: Developer Preview**
+ * Options used to configure the result of the `useDetailPage` hook.
  *
- * @docsCategory hooks
+ * @docsCategory detail-views
  * @docsPage useDetailPage
  * @since 3.3.0
  */
@@ -148,9 +148,8 @@ export type DetailPageEntity<
 
 /**
  * @description
- * **Status: Developer Preview**
  *
- * @docsCategory hooks
+ * @docsCategory detail-views
  * @docsPage useDetailPage
  * @since 3.3.0
  */
@@ -231,7 +230,7 @@ export interface UseDetailPageResult<
  * });
  * ```
  *
- * @docsCategory hooks
+ * @docsCategory detail-views
  * @docsPage useDetailPage
  * @docsWeight 0
  * @since 3.3.0

package/src/lib/graphql/api.ts

@@ -4,8 +4,8 @@ import { DocumentNode, print } from 'graphql';
 import { uiConfig } from 'virtual:vendure-ui-config';
 
 const API_URL =
-    uiConfig.api.host +
-    (uiConfig.api.port !== 'auto' ? `:${uiConfig.api.port}` : '') +
+    (uiConfig.api.host !== "auto" ? uiConfig.api.host : `${window.location.protocol}//${window.location.hostname}`) +
+    `:${(uiConfig.api.port !== 'auto' ? uiConfig.api.port : window.location.port)}` +
     `/${uiConfig.api.adminApiPath}`;
 
 export const SELECTED_CHANNEL_TOKEN_KEY = 'vendure-selected-channel-token';