@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-dashboard/creating-pages/index.md

@@ -0,0 +1,90 @@
+---
+title: 'Creating Pages'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Page Structure
+
+All pages in the Dashboard follow this structure:
+
+```tsx title="src/plugins/example/dashboard/test-page.tsx"
+import { Page, PageBlock, PageLayout, PageTitle } from '@vendure/dashboard';
+
+export function TestPage() {
+    return (
+        <Page pageId="test-page">
+            <PageTitle>Test Page</PageTitle>
+            <PageLayout>
+                <PageBlock column="main" blockId="main-stuff">
+                    This will display in the main area
+                </PageBlock>
+                <PageBlock column="side" blockId="side-stuff">
+                    This will display in the side area
+                </PageBlock>
+            </PageLayout>
+        </Page>
+    )
+}
+```
+
+- [Page component](/reference/dashboard/page-layout/page)
+  - [PageTitle component](/reference/dashboard/page-layout/page-title)
+  - [PageLayout component](/reference/dashboard/page-layout)
+    - [PageBlock components](/reference/dashboard/page-layout/page-block)
+
+Following this structure ensures that:
+- Your pages look consistent with the rest of the Dashboard
+- Your page content is responsive
+- Your page can be further extended using the [pageBlocks API](/guides/extending-the-dashboard/customizing-pages/page-blocks)
+
+:::info
+Note that the [ListPage](/reference/dashboard/list-views/list-page) and [DetailPage](/reference/dashboard/detail-views/detail-page)
+components internally use this same structure, so when using those top-level components you don't need to wrap them
+in `Page` etc.
+:::
+
+## Page Routes & Navigation
+
+Once you have defined a page component, you'll need to make it accessible to users with:
+
+- A route (url) by which it can be accessed
+- Usually a navigation bar entry in the main side navigation of the Dashboard
+
+Both of these are handled using the [DashboardRouteDefinition API](/reference/dashboard/extensions-api/routes):
+
+```tsx title="src/plugins/example/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { TestPage } from './test-page';
+
+defineDashboardExtension({
+    routes: [
+        {
+            // The TestPage will be available at e.g. 
+            // http://localhost:5173/dashboard/test
+            path: '/test',
+            // The loader function is allows us to define breadcrumbs
+            loader: () => ({ breadcrumb: 'Test Page' }),
+            // Here we define the nav menu items
+            navMenuItem: {
+                // a unique ID
+                id: 'test',
+                // the nav menu item label
+                title: 'Test Page',
+                // which section it should appear in
+                sectionId: 'catalog',
+            },
+            component: TestPage,
+        },
+    ],
+});
+```
+
+:::info
+For a complete guide to the navigation options available, see the [Navigation guide](/guides/extending-the-dashboard/navigation/)
+:::
+
+
+

package/docs/guides/extending-the-dashboard/creating-pages/list-pages.md

@@ -0,0 +1,206 @@
+---
+title: 'Creating List Pages'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Setup
+
+:::info
+This guide assumes you have a `CmsPlugin` with an `Article` entity, as covered in the [Extending the Dashboard: Plugin Setup](/guides/extending-the-dashboard/extending-overview/#plugin-setup) guide.
+:::
+
+List pages can be easily created for any query in the Admin API that follows the [PaginatedList pattern](/guides/how-to/paginated-list/).
+
+For example, the `articles` query of our `CmsPlugin` looks like this:
+
+```graphql
+type ArticleList implements PaginatedList {
+  items: [Article!]!
+  totalItems: Int!
+}
+
+extend type Query {
+  articles(options: ArticleListOptions): ArticleList!
+}
+```
+
+## List Page Example
+
+First we'll create a new `article-list.tsx` file in the `./src/plugins/cms/dashboard` directory:
+
+```tsx title="src/plugins/cms/dashboard/article-list.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
+            }
+            totalItems
+        }
+    }
+`);
+
+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>
+    ),
+};
+```
+
+Let's register this route (and we can also remove the test page) in our `index.tsx` file:
+
+```tsx title="src/plugins/cms/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+// highlight-next-line
+import { articleList } from './article-list';
+
+defineDashboardExtension({
+    routes: [
+        // highlight-next-line
+        articleList,
+    ],
+});
+```
+
+:::note
+After adding new Dashboard files to your plugin, you'll need to re-start the dev server for those
+files to be picked up by Vite:
+
+```bash
+q # to stop the running dev server
+npx vite # to restart
+```
+:::
+
+## The ListPage Component
+
+The `ListPage` component can be customized to your exact needs, such as:
+
+- Setting the columns which are visible by default
+- Setting the default order of the columns
+- Defining bulk actions ("delete all selected" etc.)
+
+See the [ListPage component reference](/reference/dashboard/list-views/list-page) for an explanation of the available options.
+
+## Customizing Columns
+
+It is common that you will want to customize the way certain columns are rendered. This is done
+using the `customizeColumns` prop on the `ListPage` component.
+
+By default, an appropriate component will be chosen to render the column data
+based on the data type of the field. However, in many cases you want to have
+more control over how the column data is rendered.
+
+```tsx
+<ListPage
+  pageId="collection-list"
+  listQuery={collectionListDocument}
+  customizeColumns={{
+      // The key "name" matches one of the top-level fields of the
+      // list query type (Collection, in this example)
+      name: {
+          meta: {
+              // The Dashboard optimizes the list query `collectionListDocument` to
+              // only select field that are actually visible in the ListPage table.
+              // However, sometimes you want to render data from other fields, i.e.
+              // this column has a data dependency on the "children" and "breadcrumbs"
+              // fields in order to correctly render the "name" field.
+              // In this case, we can declare those data dependencies which means whenever
+              // the "name" column is visible, it will ensure the "children" and "breadcrumbs"
+              // fields are also selected in the query.
+              dependencies: ['children', 'breadcrumbs'],
+          },
+          header: 'Collection Name',
+          cell: ({ row }) => {
+              const isExpanded = row.getIsExpanded();
+              const hasChildren = !!row.original.children?.length;
+              return (
+                  <div
+                      style={{ marginLeft: (row.original.breadcrumbs?.length - 2) * 20 + 'px' }}
+                      className="flex gap-2 items-center"
+                  >
+                      <Button
+                          size="icon"
+                          variant="secondary"
+                          onClick={row.getToggleExpandedHandler()}
+                          disabled={!hasChildren}
+                          className={!hasChildren ? 'opacity-20' : ''}
+                      >
+                          {isExpanded ? <FolderOpen /> : <Folder />}
+                      </Button>
+                      <DetailPageButton id={row.original.id} label={row.original.name} />
+                  </div>
+              );
+          },
+      },
+  }}
+/>
+```

package/docs/guides/extending-the-dashboard/creating-pages/tabbed-pages.md

@@ -0,0 +1,144 @@
+---
+title: 'Creating Tabbed Pages'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Setup
+
+:::info
+This guide assumes you have a basic understanding of creating custom pages in the Vendure Dashboard, as covered in the [Creating List Pages](/guides/extending-the-dashboard/creating-pages/list-pages) and [Creating Detail Pages](/guides/extending-the-dashboard/creating-pages/detail-pages) guides.
+:::
+
+Tabbed pages allow you to organize related content into separate tabs within a single page. This is useful
+for grouping configuration settings, related data views, or different aspects of an entity.
+
+While using them within page blocks is supported, by simply using the `Tabs` component directly, you may want to use `Tabs` on the top level of your page.
+This is where this guide comes in.
+
+## Tabbed Page Example
+
+![Tabbed Page Example](./tabbed-page-example.webp)
+
+The Dashboard provides tab components that work seamlessly with the `Page` component to create tabbed interfaces.
+Using the correct format is important to avoid style issues and ensure consistent behavior.
+
+When a component grows, you may want to consider using the `Tabs` component to help you organize your content.
+
+```tsx title="src/plugins/my-plugin/dashboard/settings-page.tsx"
+import {
+    Page,
+    PageTitle,
+    Tabs,
+    TabsContent,
+    TabsList,
+    TabsTrigger,
+    DashboardRouteDefinition,
+} from '@vendure/dashboard';
+
+export const settingsPage: DashboardRouteDefinition = {
+    navMenuItem: { sectionId: 'settings', title: 'My Settings', order: 10 },
+    path: '/settings/my-settings',
+    loader: () => ({
+        breadcrumb: 'My Settings',
+    }),
+    component: () => {
+        return (
+            <Page pageId="my-settings">
+                <PageTitle>My Tabbed Page</PageTitle>
+
+                <Tabs defaultValue="main-stuff" className="w-full">
+                    <TabsList>
+                        <TabsTrigger value="main-stuff">main stuff</TabsTrigger>
+                        <TabsTrigger value="other-stuff">other stuff</TabsTrigger>
+                    </TabsList>
+
+                    <TabsContent value="main-stuff">
+                        <PageLayout>
+                            <PageBlock column="main" blockId="main-stuff">
+                                This will display in the main area *in a tab*
+                            </PageBlock>
+                        </PageLayout>
+                    </TabsContent>
+
+                    <TabsContent value="other-stuff">
+                        <PageLayout>
+                            <PageBlock column="main" blockId="other-stuff">
+                                This will display in the main area *in another tab*
+                            </PageBlock>
+                        </PageLayout>
+                    </TabsContent>
+                </Tabs>
+            </Page>
+        );
+    },
+};
+```
+
+## Tab Component
+
+This uses the stock shadcn tab component, docs are avilable [here](https://ui.shadcn.com/docs/components/tabs).
+
+:::note
+Always use the `Page` component as the root and `PageLayout` as the only child of the `TabContent` when creating tabbed pages. This ensures proper styling
+and integration with the Dashboard layout system.
+:::
+
+## Avoiding Nested Layouts
+
+The purpose of this structure is to avoid nested layout components, which can cause style and layout issues.
+
+:::warning
+One might be tempted to wrap tab content in a `FullWidthPageBlock` or `PageLayout` and then place other `PageBlock` components inside it. **This will cause layout problems.**
+
+Instead, place `PageBlock` components directly inside each `TabsContent`, just as you would in a regular detail page.
+
+**Incorrect approach:**
+
+```tsx title="DO NOT DO THIS"
+<Tabs value="general">
+    <PageLayout>
+        // this will not render correctly
+        <FullWidthPageBlock blockId="tabbed-page">
+            <TabsList>
+                <TabsTrigger value="main-stuff">main stuff</TabsTrigger>
+                <TabsTrigger value="also-main-stuff">also main stuff</TabsTrigger>
+            </TabsList>
+
+            <TabsContent value="main-stuff">
+                <PageBlock column="main" blockId="main-stuff">
+                    This will display in the main area *in a new tab*
+                </PageBlock>
+            </TabsContent>
+        </FullWidthPageBlock>
+    </PageLayout>
+</Tabs>
+```
+
+:::
+
+## Using Tabs with Components
+
+You can use any Dashboard components within tab content, including forms, lists, or custom components:
+
+```tsx
+<TabsContent value="general">
+    <PageBlock column="main" blockId="general-settings">
+        <DetailFormGrid>
+            <FormFieldWrapper
+                control={form.control}
+                name="siteName"
+                label="Site Name"
+                render={({ field }) => <Input {...field} />}
+            />
+            <FormFieldWrapper
+                control={form.control}
+                name="siteUrl"
+                label="Site URL"
+                render={({ field }) => <Input {...field} />}
+            />
+        </DetailFormGrid>
+    </PageBlock>
+</TabsContent>
+```