@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-dashboard/navigation/index.md

@@ -0,0 +1,322 @@
+---
+title: 'Navigation'
+---
+
+The dashboard provides a flexible navigation system that allows you to add custom navigation sections and menu items. Navigation items are organized into sections that can be placed in either the "Platform" (top) or "Administration" (bottom) areas of the sidebar.
+
+## Adding Navigation Items to Existing Sections
+
+The simplest way to add navigation is to add menu items to existing sections. This is done automatically when you define routes with `navMenuItem` properties.
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+    routes: [
+        {
+            path: '/my-custom-page',
+            component: () => <div>My Custom Page</div>,
+            navMenuItem: {
+                // The section where this item should appear
+                sectionId: 'catalog',
+                // Unique identifier for this menu item
+                id: 'my-custom-page',
+                // Display text in the navigation
+                title: 'My Custom Page',
+                // Optional: URL if different from path
+                url: '/my-custom-page',
+            },
+        },
+    ],
+});
+```
+
+### Available Section IDs
+
+The dashboard comes with several built-in sections:
+
+- **`catalog`** - For product-related functionality
+- **`orders`** - For order management
+- **`customers`** - For customer management
+- **`marketing`** - For promotions and marketing tools
+- **`settings`** - For configuration and admin settings
+
+### Finding Section IDs & Ordering
+
+You can find the available IDs & their order value for all navigation sections and items using [Dev mode](/guides/extending-the-dashboard/extending-overview/#dev-mode):
+
+![Dev mode navigation ids](./dev-mode-nav.webp)
+
+## Creating Custom Navigation Sections
+
+You can create entirely new navigation sections with their own icons and ordering:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+import { FileTextIcon, SettingsIcon } from 'lucide-react';
+
+defineDashboardExtension({
+    // Define custom navigation sections
+    navSections: [
+        {
+            id: 'content-management',
+            title: 'Content',
+            icon: FileTextIcon,
+            placement: 'top', // Platform area
+            order: 350, // After Customers (400), before Marketing (500)
+        },
+        {
+            id: 'integrations',
+            title: 'Integrations',
+            icon: SettingsIcon,
+            placement: 'bottom', // Administration area
+            order: 150, // Between System (100) and Settings (200)
+        },
+    ],
+    routes: [
+        {
+            path: '/articles',
+            component: () => <div>Articles</div>,
+            navMenuItem: {
+                sectionId: 'content-management', // Use our custom section
+                id: 'articles',
+                title: 'Articles',
+            },
+        },
+        {
+            path: '/pages',
+            component: () => <div>Pages</div>,
+            navMenuItem: {
+                sectionId: 'content-management',
+                id: 'pages',
+                title: 'Pages',
+            },
+        },
+    ],
+});
+```
+
+For documentation on all the configuration properties available, see the reference docs:
+
+- [DashboardNavSectionDefinition](/reference/dashboard/extensions-api/navigation#dashboardnavsectiondefinition)
+- [NavMenuItem](/reference/dashboard/extensions-api/navigation#navmenuitem)
+
+## Section Placement and Ordering
+
+The navigation sidebar is divided into two areas:
+
+- **Top Placement (`'top'`)**: The "Platform" area for core functionality (Dashboard, Catalog, Sales, etc.)
+- **Bottom Placement (`'bottom'`)**: The "Administration" area for system and configuration sections (System, Settings)
+
+### Placement Examples
+
+```tsx
+defineDashboardExtension({
+    navSections: [
+        {
+            id: 'reports',
+            title: 'Reports',
+            icon: BarChartIcon,
+            placement: 'top', // Appears in Platform area
+            order: 150, // Positioned within top sections
+        },
+        {
+            id: 'integrations',
+            title: 'Integrations',
+            icon: PlugIcon,
+            placement: 'bottom', // Appears in Administration area
+            order: 150, // Positioned within bottom sections
+        },
+    ],
+});
+```
+
+### Order Scoping
+
+:::important Order Scoping
+Order values are scoped within each placement area. This means:
+
+- Top sections compete only with other top sections for positioning
+- Bottom sections compete only with other bottom sections for positioning
+- You can use the same order value in both top and bottom without conflict
+  :::
+
+### Default Section Orders
+
+**Top Placement (Platform):**
+
+- Dashboard: 100
+- Catalog: 200
+- Sales: 300
+- Customers: 400
+- Marketing: 500
+
+**Bottom Placement (Administration):**
+
+- System: 100
+- Settings: 200
+
+This means if you want to add a section between Catalog and Sales in the top area, you might use `order: 250`. If you want to add a section before Settings in the bottom area, you could use `order: 150`.
+
+:::note Default Placement
+If you don't specify a `placement`, sections default to `'top'` placement.
+:::
+
+## Unauthenticated Routes
+
+By default, all navigation is assumed to be for authenticated routes, i.e. the routes are only accessible to administrators
+who are logged in.
+
+Sometimes you want to make a certain route accessible to unauthenticated users. For example, you may want to implement
+a completely custom login page or a password recovery page, which must be accessible to everyone.
+
+This is done by setting `authenticated: false` in your route definition:
+
+```tsx
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+    routes: [
+        {
+            path: '/public',
+            component: () => (
+                <div className="flex h-screen items-center justify-center text-2xl">This is a public page!</div>
+            ),
+            // highlight-next-line
+            authenticated: false
+        },
+    ]
+});
+```
+
+This page will then be accessible to all users at `http://localhost:4873/dashboard/public`
+
+![Unauthenticated page](./unauthenticated-page.webp)
+
+## Complete Example
+
+Here's a comprehensive example showing how to create a complete navigation structure for a content management system:
+
+```tsx title="src/plugins/cms/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+import { FileTextIcon, ImageIcon, TagIcon, FolderIcon, SettingsIcon } from 'lucide-react';
+
+defineDashboardExtension({
+    // Create custom navigation sections
+    navSections: [
+        {
+            id: 'content',
+            title: 'Content',
+            icon: FileTextIcon,
+            placement: 'top', // Platform area
+            order: 250, // Between Catalog (200) and Sales (300)
+        },
+        {
+            id: 'media',
+            title: 'Media',
+            icon: ImageIcon,
+            placement: 'top', // Platform area
+            order: 275, // After Content section
+        },
+    ],
+
+    routes: [
+        // Content section items
+        {
+            path: '/articles',
+            component: () => <div>Articles List</div>,
+            navMenuItem: {
+                sectionId: 'content',
+                id: 'articles',
+                title: 'Articles',
+            },
+        },
+        {
+            path: '/pages',
+            component: () => <div>Pages List</div>,
+            navMenuItem: {
+                sectionId: 'content',
+                id: 'pages',
+                title: 'Pages',
+            },
+        },
+        {
+            path: '/categories',
+            component: () => <div>Categories List</div>,
+            navMenuItem: {
+                sectionId: 'content',
+                id: 'categories',
+                title: 'Categories',
+            },
+        },
+
+        // Media section items
+        {
+            path: '/media-library',
+            component: () => <div>Media Library</div>,
+            navMenuItem: {
+                sectionId: 'media',
+                id: 'media-library',
+                title: 'Library',
+            },
+        },
+        {
+            path: '/media-folders',
+            component: () => <div>Media Folders</div>,
+            navMenuItem: {
+                sectionId: 'media',
+                id: 'media-folders',
+                title: 'Folders',
+            },
+        },
+
+        // Add to existing settings section
+        {
+            path: '/cms-settings',
+            component: () => <div>CMS Settings</div>,
+            navMenuItem: {
+                sectionId: 'settings',
+                id: 'cms-settings',
+                title: 'CMS Settings',
+            },
+        },
+    ],
+});
+```
+
+## Icons
+
+The dashboard uses [Lucide React](https://lucide.dev/) icons. You can import any icon from the library:
+
+```tsx
+import {
+    HomeIcon,
+    ShoppingCartIcon,
+    UsersIcon,
+    SettingsIcon,
+    FileTextIcon,
+    ImageIcon,
+    BarChartIcon,
+    // ... any other Lucide icon
+} from 'lucide-react';
+```
+
+Common icons for navigation sections:
+
+- **Content**: `FileTextIcon`, `EditIcon`, `BookOpenIcon`
+- **Media**: `ImageIcon`, `FolderIcon`, `UploadIcon`
+- **Analytics**: `BarChartIcon`, `TrendingUpIcon`, `PieChartIcon`
+- **Tools**: `WrenchIcon`, `SettingsIcon`, `CogIcon`
+- **Integrations**: `LinkIcon`, `ZapIcon`, `PlugIcon`
+
+## Best Practices
+
+:::tip Navigation Design Guidelines
+
+1. **Use descriptive section names**: Choose clear, concise names that indicate the section's purpose
+2. **Group related functionality**: Keep logically related menu items in the same section
+3. **Choose appropriate icons**: Select icons that clearly represent the section's function
+4. **Consider ordering carefully**: Place frequently used sections earlier in the navigation
+5. **Keep section counts reasonable**: Avoid creating too many sections as it can clutter the navigation
+6. **Use consistent naming**: Follow consistent patterns for menu item names within sections
+   :::

package/docs/guides/extending-the-dashboard/tech-stack/index.md

@@ -0,0 +1,395 @@
+---
+title: 'Tech Stack'
+---
+
+The Vendure Dashboard is built on a modern stack of technologies that provide a great developer experience and powerful capabilities for building custom extensions.
+
+## Core Technologies
+
+### React 19
+
+The dashboard is built with [React 19](https://react.dev/), giving you access to all the latest React features including:
+
+- React Compiler optimizations
+- Improved concurrent features
+- Actions and form handling improvements
+- Enhanced automatic batching
+- Better TypeScript support
+- New hooks like `useOptimistic` and `useFormStatus`
+
+```tsx
+import { useOptimistic, useFormStatus } from 'react';
+
+function OptimisticUpdateExample() {
+    const [optimisticState, addOptimistic] = useOptimistic(state, (currentState, optimisticValue) => {
+        // Return new state with optimistic update
+        return [...currentState, optimisticValue];
+    });
+
+    return (
+        <div>
+            {optimisticState.map(item => (
+                <div key={item.id}>{item.name}</div>
+            ))}
+        </div>
+    );
+}
+
+function SubmitButton() {
+    const { pending } = useFormStatus();
+
+    return (
+        <button type="submit" disabled={pending}>
+            {pending ? 'Saving...' : 'Save'}
+        </button>
+    );
+}
+```
+
+### TypeScript
+
+Full [TypeScript](https://www.typescriptlang.org/) support throughout the dashboard provides:
+
+- Type safety for your custom components
+- IntelliSense and autocomplete in your IDE
+- Compile-time error checking
+- Generated types from your GraphQL schema
+
+### Vite 6
+
+[Vite 6](https://vite.dev/) powers the development experience with:
+
+- Lightning-fast hot module replacement (HMR)
+- Optimized build process with Rollup 4
+- Modern ES modules support
+- Rich plugin ecosystem
+- Environment API for better multi-environment support
+
+## UI Framework
+
+### Tailwind CSS v4
+
+The dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling:
+
+- Utility-first CSS framework
+- Improved performance with Rust-based engine
+- Enhanced CSS-first configuration
+- Responsive design system
+- Built-in dark mode support
+- Customizable design tokens
+
+```tsx
+// Example using Tailwind classes
+function MyComponent() {
+    return (
+        <div className="p-4 bg-white dark:bg-gray-800 rounded-lg shadow-md">
+            <h2 className="text-lg font-semibold text-gray-900 dark:text-white">My Custom Component</h2>
+        </div>
+    );
+}
+```
+
+### Shadcn/ui
+
+Built on top of [Radix UI](https://www.radix-ui.com/) primitives, [Shadcn/ui](https://ui.shadcn.com/) provides:
+
+- Accessible components out of the box
+- Consistent design system
+- Customizable component library
+- Copy-and-paste component approach
+
+```tsx
+import { Button, Input, Card } from '@vendure/dashboard';
+
+function MyForm() {
+    return (
+        <Card className="p-6">
+            <Input placeholder="Enter your text" />
+            <Button className="mt-4">Submit</Button>
+        </Card>
+    );
+}
+```
+
+## Data Layer: TanStack Query
+
+[TanStack Query](https://tanstack.com/query) v5 handles all data fetching and server state management:
+
+- Automatic caching and synchronization
+- Background updates
+- Optimistic updates
+- Error handling and retry logic
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { graphql } from '@/gql';
+
+const getProductsQuery = graphql(`
+    query GetProducts {
+        products {
+            items {
+                id
+                name
+                slug
+            }
+        }
+    }
+`);
+
+function ProductList() {
+    const { data, isLoading, error } = useQuery({
+        queryKey: ['products'],
+        queryFn: () => client.request(getProductsQuery),
+    });
+
+    if (isLoading) return <div>Loading...</div>;
+    if (error) return <div>Error: {error.message}</div>;
+
+    return (
+        <ul>
+            {data.products.items.map(product => (
+                <li key={product.id}>{product.name}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+## Routing: TanStack Router
+
+[TanStack Router](https://tanstack.com/router) provides type-safe routing with:
+
+- File-based routing
+- 100% type-safe navigation
+- Automatic route validation
+- Search params handling
+- Built-in caching and preloading
+- Route-level code splitting
+
+```tsx
+import { Link, useNavigate } from '@tanstack/react-router';
+
+function Navigation() {
+    const navigate = useNavigate();
+
+    return (
+        <div>
+            <Link to="/products">Products</Link>
+            <button onClick={() => navigate({ to: '/customers' })}>Go to Customers</button>
+        </div>
+    );
+}
+```
+
+## Forms: React Hook Form
+
+[React Hook Form](https://react-hook-form.com/) provides powerful form handling with:
+
+- Minimal re-renders
+- Built-in validation
+- TypeScript support
+- Easy integration with UI libraries
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { FormFieldWrapper, Input, Button } from '@vendure/dashboard';
+
+interface FormData {
+    name: string;
+    email: string;
+}
+
+function MyForm() {
+    const form = useForm<FormData>();
+
+    const onSubmit = (data: FormData) => {
+        console.log(data);
+    };
+
+    return (
+        <form onSubmit={form.handleSubmit(onSubmit)}>
+            <FormFieldWrapper
+                control={form.control}
+                name="name"
+                label="Name"
+                render={({ field }) => <Input {...field} />}
+            />
+            <FormFieldWrapper
+                control={form.control}
+                name="email"
+                label="Email"
+                render={({ field }) => <Input type="email" {...field} />}
+            />
+            <Button type="submit">Submit</Button>
+        </form>
+    );
+}
+```
+
+## GraphQL Integration: gql.tada
+
+[gql.tada](https://gql-tada.0no.co/) provides type-safe GraphQL with:
+
+- Generated TypeScript types
+- IntelliSense for queries and mutations
+- Compile-time validation
+- Schema introspection
+
+```tsx
+import { graphql } from '@/gql';
+import { useMutation } from '@tanstack/react-query';
+
+const createProductMutation = graphql(`
+    mutation CreateProduct($input: CreateProductInput!) {
+        createProduct(input: $input) {
+            id
+            name
+            slug
+        }
+    }
+`);
+
+function CreateProductForm() {
+    const mutation = useMutation({
+        mutationFn: (input: CreateProductInput) => client.request(createProductMutation, { input }),
+    });
+
+    // TypeScript knows the exact shape of the input and response
+    const handleSubmit = (data: CreateProductInput) => {
+        mutation.mutate(data);
+    };
+
+    return (
+        // Form implementation
+        <div>Create Product Form</div>
+    );
+}
+```
+
+## Notifications: Sonner
+
+[Sonner](https://sonner.emilkowal.ski/) provides toast notifications with:
+
+- Beautiful animations
+- Customizable appearance
+- Promise-based notifications
+- Stacking support
+
+```tsx
+import { toast } from 'sonner';
+
+function MyComponent() {
+    const handleSave = async () => {
+        try {
+            await saveData();
+            toast.success('Data saved successfully!');
+        } catch (error) {
+            toast.error('Failed to save data', {
+                description: error.message,
+            });
+        }
+    };
+
+    // Promise-based toasts
+    const handleAsyncAction = () => {
+        toast.promise(performAsyncAction(), {
+            loading: 'Saving...',
+            success: 'Saved successfully!',
+            error: 'Failed to save',
+        });
+    };
+
+    return (
+        <div>
+            <button onClick={handleSave}>Save</button>
+            <button onClick={handleAsyncAction}>Async Save</button>
+        </div>
+    );
+}
+```
+
+## Icons: Lucide React
+
+[Lucide React](https://lucide.dev/) provides beautiful, customizable icons:
+
+- Consistent design
+- Tree-shakeable
+- Customizable size and color
+- Accessible by default
+
+```tsx
+import { ShoppingCartIcon, UserIcon, SettingsIcon } from 'lucide-react';
+
+function Navigation() {
+    return (
+        <nav className="flex space-x-4">
+            <a href="/products" className="flex items-center">
+                <ShoppingCartIcon className="mr-2 h-4 w-4" />
+                Products
+            </a>
+            <a href="/customers" className="flex items-center">
+                <UserIcon className="mr-2 h-4 w-4" />
+                Customers
+            </a>
+            <a href="/settings" className="flex items-center">
+                <SettingsIcon className="mr-2 h-4 w-4" />
+                Settings
+            </a>
+        </nav>
+    );
+}
+```
+
+## Animations: Motion
+
+Smooth animations powered by [Motion](https://motion.dev/) (successor to Framer Motion):
+
+- High-performance animations
+- Declarative API
+- Spring-based animations
+- Layout animations
+- Gesture support
+
+```tsx
+import { motion } from 'motion/react';
+
+function AnimatedCard({ children }) {
+    return (
+        <motion.div
+            initial={{ opacity: 0, y: 20 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -20 }}
+            className="bg-white p-6 rounded-lg shadow"
+        >
+            {children}
+        </motion.div>
+    );
+}
+```
+
+## Internationalization: Lingui
+
+[Lingui](https://lingui.dev/) provides a powerful i18n solution for React:
+
+- ICU MessageFormat support
+- Automatic message extraction
+- TypeScript integration
+- Pluralization support
+- Compile-time optimization
+
+```tsx
+import { Trans, useLingui } from '@lingui/react/macro';
+
+function MyComponent() {
+    const { t } = useLingui();
+
+    return (
+        <div>
+            <h1>
+                <Trans>Welcome to Dashboard</Trans>
+            </h1>
+            <p>{t`Click here to continue`}</p>
+        </div>
+    );
+}
+```