docs(dashboard): Update inline doc blocks (#3714)

Co-authored-by: Housein Abo Shaar <76689341+GogoIsProgramming@users.noreply.github.com>
Co-authored-by: Michael Bromley <michael@michaelbromley.co.uk>

packages/dashboard/src/lib/framework/extension-api/extension-api-types.ts

@@ -55,8 +55,7 @@ export interface DashboardExtension {
     widgets?: DashboardWidgetDefinition[];
     /**
      * @description
-     * Unified registration for custom form components including custom field components,
-     * input components, and display components.
+     * Unified registration for custom form custom field components.
      */
     customFormComponents?: DashboardCustomFormComponents;
     /**
@@ -64,6 +63,10 @@ export interface DashboardExtension {
      * Allows you to customize aspects of existing data tables in the dashboard.
      */
     dataTables?: DashboardDataTableExtensionDefinition[];
+    /**
+     * @description
+     * Allows you to customize the detail form for any page in the dashboard.
+     */
     detailForms?: DashboardDetailFormExtensionDefinition[];
     /**
      * @description

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

@@ -7,6 +7,7 @@ import { DocumentNode } from 'graphql';
  * The pageId is already defined in the data table extension, so only the column name is needed.
  *
  * @docsCategory extensions
+ * @docsPage DataTable
  * @since 3.4.0
  */
 export interface DashboardDataTableDisplayComponent {
@@ -39,21 +40,29 @@ export type BulkActionComponent<Item extends { id: string } & Record<string, any
  * A bulk action is a component that will be rendered in the bulk actions dropdown.
  *
  * @docsCategory components
- * @docsPage DataTableBulkActions
+ * @docsPage DataTable
  * @since 3.4.0
  */
 export type BulkAction = {
+    /**
+     * @description
+     * Optional order number to control the position of this bulk action in the dropdown.
+     * A larger number will appear lower in the list.
+     */
     order?: number;
+    /**
+     * @description
+     * The React component that will be rendered as the bulk action item.
+     */
     component: BulkActionComponent<any>;
 };
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * This allows you to customize aspects of existing data tables in the dashboard.
  *
  * @docsCategory extensions
+ * @docsPage DataTable
  * @since 3.4.0
  */
 export interface DashboardDataTableExtensionDefinition {

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

@@ -10,6 +10,7 @@ import { DocumentNode } from 'graphql';
  * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
  *
  * @docsCategory extensions
+ * @docsPage DetailForms
  * @since 3.4.0
  */
 export interface DashboardDetailFormInputComponent {
@@ -37,6 +38,7 @@ export interface DashboardDetailFormInputComponent {
  * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
  *
  * @docsCategory extensions
+ * @docsPage DetailForms
  * @since 3.4.0
  */
 export interface DashboardDetailFormDisplayComponent {
@@ -58,6 +60,15 @@ export interface DashboardDetailFormDisplayComponent {
     component: DataDisplayComponent;
 }
 
+/**
+ * @description
+ * Allows you to extend existing detail forms (e.g. on the product detail or customer detail pages)
+ * with custom GraphQL queries, input components, and display components.
+ *
+ * @since 3.4.0
+ * @docsPage DetailForms
+ * @docsCategory extensions
+ */
 export interface DashboardDetailFormExtensionDefinition {
     /**
      * @description
@@ -66,6 +77,8 @@ export interface DashboardDetailFormExtensionDefinition {
     pageId: string;
     /**
      * @description
+     * Extends the GraphQL query used to fetch data for the detail page, allowing you to add additional
+     * fields that can be used by custom input or display components.
      */
     extendDetailDocument?: string | DocumentNode | (() => DocumentNode | string);
     /**

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

@@ -7,10 +7,20 @@ import { CustomFormComponentInputProps } from '../../form-engine/custom-form-com
  * Allows you to define custom form components for custom fields in the dashboard.
  *
  * @docsCategory extensions
+ * @docsPage FormComponents
  * @since 3.4.0
  */
 export interface DashboardCustomFormComponent {
+    /**
+     * @description
+     * A unique identifier for the custom form component. It is a good practice to namespace
+     * these IDs to avoid naming collisions, for example `"my-plugin.markdown-editor"`.
+     */
     id: string;
+    /**
+     * @description
+     * The React component that will be rendered as the custom form input.
+     */
     component: React.FunctionComponent<CustomFormComponentInputProps>;
 }
 
@@ -20,6 +30,7 @@ export interface DashboardCustomFormComponent {
  * For input and display components, use the co-located approach with detailForms.
  *
  * @docsCategory extensions
+ * @docsPage FormComponents
  * @since 3.4.0
  */
 export interface DashboardCustomFormComponents {

packages/dashboard/src/lib/framework/extension-api/types/layout.ts

@@ -9,11 +9,10 @@ export interface ActionBarButtonState {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Allows you to define custom action bar items for any page in the dashboard.
  *
  * @docsCategory extensions
+ * @docsPage Layout
  * @since 3.3.0
  */
 export interface DashboardActionBarItem {
@@ -59,13 +58,12 @@ export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | '
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * The location of a page block in the dashboard. The location can be found by turning on
  * "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
  * @since 3.3.0
  */
 export type PageBlockLocation = {
@@ -76,12 +74,11 @@ export type PageBlockLocation = {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * This allows you to insert a custom component into a specific location
  * on any page in the dashboard.
  *
  * @docsCategory extensions
+ * @docsPage Layout
  * @since 3.3.0
  */
 export interface DashboardPageBlockDefinition {

packages/dashboard/src/lib/framework/extension-api/types/login.ts

@@ -2,12 +2,11 @@ import type React from 'react';
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Defines a custom logo component for the login page.
  *
  * @docsCategory extensions
- * @since 3.3.0
+ * @docsPage Login
+ * @since 3.4.0
  */
 export interface LoginLogoExtension {
     /**
@@ -19,12 +18,11 @@ export interface LoginLogoExtension {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Defines content to display before the login form.
  *
  * @docsCategory extensions
- * @since 3.3.0
+ * @docsPage Login
+ * @since 3.4.0
  */
 export interface LoginBeforeFormExtension {
     /**
@@ -36,12 +34,11 @@ export interface LoginBeforeFormExtension {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Defines content to display after the login form.
  *
  * @docsCategory extensions
- * @since 3.3.0
+ * @docsPage Login
+ * @since 3.4.0
  */
 export interface LoginAfterFormExtension {
     /**
@@ -53,12 +50,11 @@ export interface LoginAfterFormExtension {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Defines a custom login image component that replaces the default image panel.
  *
  * @docsCategory extensions
- * @since 3.3.0
+ * @docsPage Login
+ * @since 3.4.0
  */
 export interface LoginImageExtension {
     /**
@@ -70,12 +66,11 @@ export interface LoginImageExtension {
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Defines all available login page extensions.
  *
  * @docsCategory extensions
- * @since 3.3.0
+ * @docsPage Login
+ * @since 3.4.0
  */
 export interface DashboardLoginExtensions {
     /**

packages/dashboard/src/lib/framework/extension-api/types/navigation.ts

@@ -4,16 +4,73 @@ import type React from 'react';
 
 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
+ * @since 3.4.0
+ */
 export interface DashboardRouteDefinition {
+    /**
+     * @description
+     * The React component that will be rendered for this route.
+     */
     component: (route: AnyRoute) => React.ReactNode;
+    /**
+     * @description
+     * The URL path for this route, e.g. '/my-custom-page'.
+     */
     path: string;
+    /**
+     * @description
+     * Optional navigation menu item configuration to add this route to the nav menu
+     * on the left side of the dashboard.
+     */
     navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
+    /**
+     * @description
+     * Optional loader function to fetch data before the route renders.
+     * The value is a Tanstack Router
+     * [loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)
+     */
     loader?: RouteOptions['loader'];
 }
 
+/**
+ * @description
+ * Defines a custom navigation section in the dashboard sidebar.
+ *
+ * @docsCategory extensions
+ * @docsPage Navigation
+ * @since 3.4.0
+ */
 export interface DashboardNavSectionDefinition {
+    /**
+     * @description
+     * A unique identifier for the navigation section.
+     */
     id: string;
+    /**
+     * @description
+     * The display title for the navigation section.
+     */
     title: string;
+    /**
+     * @description
+     * Optional icon to display next to the section title. The icons should
+     * be imported from `'lucide-react'`.
+     *
+     * @example
+     * ```ts
+     * import { PlusIcon } from 'lucide-react';
+     * ```
+     */
     icon?: LucideIcon;
+    /**
+     * @description
+     * Optional order number to control the position of this section in the sidebar.
+     */
     order?: number;
 }

packages/dashboard/src/lib/framework/extension-api/types/widgets.ts

@@ -2,8 +2,6 @@ import React, { PropsWithChildren } from 'react';
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Base props interface for dashboard widgets.
  *
  * @docsCategory extensions
@@ -19,8 +17,6 @@ export type DashboardBaseWidgetProps = PropsWithChildren<{
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * Represents an instance of a dashboard widget with its layout and configuration.
  *
  * @docsCategory extensions