@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-admin-ui/add-actions-to-pages/index.md

@@ -0,0 +1,233 @@
+---
+title: 'Page ActionBar Buttons'
+weight: 5
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The `ActionBar` is the horizontal area at the top of each list or detail page, which contains the main buttons for that page.
+This guide explains how to add new buttons and dropdown menu items to the ActionBar.
+
+For example, consider an "order invoice" extension that allows you to print invoices for orders. You can add a "print invoice" 
+button to the ActionBar of the order detail page, either as a button or as a dropdown menu item.
+
+## ActionBar button example
+
+Adding a button is done using the [`addActionBarItem`](/reference/admin-ui-api/action-bar/add-action-bar-item/) function.
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarItem({
+        id: 'print-invoice',
+        locationId: 'order-detail',
+        label: 'Print invoice',
+        icon: 'printer',
+        routerLink: route => {
+            const id = route.snapshot.params.id;
+            return ['./extensions/order-invoices', id];
+        },
+        requiresPermission: 'ReadOrder',
+    }),
+];
+```
+
+![./ui-extensions-actionbar.webp](./ui-extensions-actionbar.webp)
+
+In each list or detail view in the app, the ActionBar has a unique `locationId` which is how the app knows in which view to place your button.
+The complete list of available locations into which you can add new ActionBar can be found in the [PageLocationId docs](/reference/admin-ui-api/action-bar/page-location-id/).
+You can also press `ctrl + u` when in development mode to see the location of all UI extension points.
+
+## ActionBar dropdown menu example
+
+Vendure v2.2.0 introduced the ability to add dropdown menu items to the ActionBar. If you want to add an action which is
+less commonly used, or want to take up less space in the action bar, then a dropdown menu item is a good choice.
+This is done using the [`addActionBarDropdownMenuItem`](/reference/admin-ui-api/action-bar/add-action-bar-dropdown-menu-item/) function.
+
+Let's re-work the "print invoice" button example to display it instead as a dropdown menu item:
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { addActionBarDropdownMenuItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarDropdownMenuItem({
+        id: 'print-invoice',
+        locationId: 'order-detail',
+        label: 'Print invoice',
+        icon: 'printer',
+        routerLink: route => {
+            const id = route.snapshot.params.id;
+            return ['./extensions/order-invoices', id];
+        },
+        requiresPermission: 'ReadOrder',
+        // When set to `true`, a horizontal divider will be
+        // displayed above this item in the dropdown menu.
+        hasDivider: true,
+    }),
+];
+```
+
+![./ui-extensions-actionbar-dropdown.webp](./ui-extensions-actionbar-dropdown.webp)
+
+## Handling button clicks
+
+There are two ways to handle the click event of an ActionBar button or dropdown menu item:
+
+1. Use the `routerLink` property to navigate to a new route when the button is clicked.
+2. Use the `onClick` property to execute a function when the button is clicked.
+
+### Using routerLink
+
+The `routerLink` property allows you to specify a route to navigate to when the button is clicked. The route can be a constant value, or it can be a function which receives the current route as well as a [`context` object](/reference/admin-ui-api/action-bar/action-bar-context) as arguments.
+
+<Tabs>
+<TabItem value="routerLink constant" label="routerLink constant" default>
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarItem({
+        id: 'print-invoice',
+        label: 'Print invoice',
+        locationId: 'order-detail',
+        // highlight-start
+        // The route can be a constant value...
+        routerLink: ['./extensions/order-invoices'],
+        // highlight-end
+    }),
+];
+```
+
+</TabItem>
+<TabItem value="routerLink function" label="routerLink function">
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarItem({
+        id: 'print-invoice',
+        label: 'Print invoice',
+        locationId: 'order-detail',
+        // highlight-start
+        // The route can be a function
+        routerLink: route => {
+            const id = route.snapshot.params.id;
+            return ['./extensions/order-invoices', id];
+        },
+        // highlight-end
+    }),
+];
+```
+
+</TabItem>
+</Tabs>
+
+### Using onClick
+
+The onClick property of the addActionBarItem function allows you to define a function that will be executed when the ActionBar button is clicked. This function receives two arguments: the click event and the current context.
+
+The context object provides access to commonly-used services, which allows you to perform GraphQL queries and mutations, and the current route, which can be used to get parameters from the URL.
+
+Here's an example of how to use the onClick property to perform a GraphQL mutation when the ActionBar button is clicked:
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import gql from 'graphql-tag';
+import { firstValueFrom } from 'rxjs';
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+const mutation = gql`
+    mutation MyMutation($orderId: ID!) {
+        myMutation(orderId: $orderId)
+    }
+`;
+
+export default [
+    addActionBarItem({
+        id: 'myButtonId',
+        label: 'My Button Label',
+        locationId: 'order-detail',
+        // highlight-start
+        onClick: async (event, context) => {
+            try {
+                const orderId = context.route.snapshot.params.id;
+                await firstValueFrom(context.dataService.mutate(mutation, { orderId }));
+            } catch (error) {
+                context.notificationService.error('Error executing mutation: ' + error.message);
+            }
+        },
+        // highlight-end
+    }),
+];
+```
+
+In this example, clicking the ActionBar button triggers a GraphQL mutation. The `context.dataService` is utilized to execute the mutation. It can also be employed to retrieve additional information about the current order if needed. The `context.route` is used to extract the ID of the current order from the URL.
+
+The utility function `firstValueFrom` from the RxJS library is used in this example to convert the Observable returned by `context.dataService.mutate(...)` into a Promise. This conversion allows the use of the `await` keyword to pause execution until the Observable emits its first value or completes.
+
+## Setting visibility & disabled state
+
+Use the `buttonState` property (added in v2.1) to control the visibility and disabled state of the button. This property is a function which receives the current context as an argument and returns an Observable of the button state:
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { map, switchMap } from 'rxjs/operators';
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarItem({
+        id: 'print-invoice',
+        label: 'Print invoice',
+        locationId: 'order-detail',
+        buttonState: context => {
+            // For any of the detail pages, we can get an observable stream
+            // of the entity via `context.entity$`:
+            return context.entity$.pipe(
+                map(order => ({
+                    disabled: order?.state === 'AddingItems',
+                    visible: true,
+                })),
+            );
+        },
+    }),
+];
+```
+
+:::note
+The `context.entity$` property was introduced in Vendure v2.2. If you are using v2.1, you can achieve equivalent functionality
+with this code:
+
+```ts
+buttonState: context => {
+    return context.route.data.pipe(
+        switchMap(data => data.detail.entity),
+        map((order: any) => ({
+            disabled: order.state === 'AddingItems',
+            visible: true,
+        })),
+    );
+}
+```
+
+:::
+
+## Restricting access by permissions
+
+You can use the `requiresPermission` property to restrict access to the button by permission. This property accepts a single permission string or an array of permission strings. If the current user does not have the required permission, the button will not be visible.
+
+```ts title="src/plugins/invoice/ui/providers.ts"
+import { addActionBarItem } from '@vendure/admin-ui/core';
+
+export default [
+    addActionBarItem({
+        id: 'print-invoice',
+        label: 'Print invoice',
+        locationId: 'order-detail',
+        routerLink: ['./extensions/order-invoices'],
+        // highlight-next-line
+        requiresPermission: 'CreateInvoice',
+    }),
+];
+```

package/docs/guides/extending-the-admin-ui/adding-ui-translations/index.md

@@ -0,0 +1,113 @@
+---
+title: 'Adding UI Translations'
+---
+
+The Vendure Admin UI is fully localizable, allowing you to:
+
+* create custom translations for your UI extensions
+* override existing translations
+* add complete translations for whole new languages
+
+![The UI language is set from the User menu](./ui-translations-01.webp)
+
+## Translation format
+
+The Admin UI uses the [Messageformat](https://messageformat.github.io/messageformat/) specification to convert i18n tokens to localized strings in the browser. Each language should have a corresponding JSON file containing the translations for that language.
+
+Here is an excerpt from the `en.json` file that ships with the Admin UI:
+
+```JSON title="en.json"
+{
+  "admin": {
+    "create-new-administrator": "Create new administrator"
+  },
+  "asset": {
+    "add-asset": "Add asset",
+    "add-asset-with-count": "Add {count, plural, 0 {assets} one {1 asset} other {{count} assets}}",
+    "assets-selected-count": "{ count } assets selected",
+    "dimensions": "Dimensions"
+  }
+}
+```
+
+The translation tokens are grouped into a single-level deep nested structure. In the Angular code, these are referenced like this: 
+
+```HTML
+<label>{{ 'asset.assets-selected-count' | translate:{ count } }}</label>
+```
+
+That is, the `{ ... }` represent variables that are passed from the application code and interpolated into the final localized string.
+
+## Adding a new language
+
+The Admin UI ships with built-in support for many languages, but allows you to add support for any other language without the need to modify the package internals.
+
+1. **Create your translation file**
+
+     Start by copying the contents of the [English language file](https://github.com/vendurehq/vendure/blob/master/packages/admin-ui/src/lib/static/i18n-messages/en.json) into a new file, `<languageCode>.json`, where `languageCode` is the 2-character [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for the language. Replace the strings with the translation for the new language.
+2. **Install `@vendure/ui-devkit`**
+
+    If not already installed, install the `@vendure/ui-devkit` package, which allows you to create custom builds of the Admin UI.
+3. **Register the translation file**
+  
+    Here's a minimal directory structure and sample code to add your new translation:
+    
+    ```text
+    /src
+    ├─ vendure-config.ts
+    └─ translations/
+        └─ ms.json
+    ```
+    
+    And the config code to register the translation file:
+    
+    ```ts title="src.vendure-config.ts"
+    import path from 'path';
+    import { VendureConfig } from '@vendure/core';
+    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+    
+    export const config: VendureConfig = {
+        // ...
+        plugins: [
+            AdminUiPlugin.init({
+                port: 3002,
+                app: compileUiExtensions({
+                    outputPath: path.join(__dirname, '../admin-ui'),
+                    extensions: [{
+                        translations: {
+                            ms: path.join(__dirname, 'translations/ms.json'),
+                        }
+                    }],
+                }),
+                adminUiConfig:{
+                    defaultLanguage: LanguageCode.ms,
+                    availableLanguages: [LanguageCode.ms, LanguageCode.en],
+                }
+            }),
+        ],
+    };
+    ```
+
+## Translating UI Extensions
+
+You can also create translations for your own UI extensions, in much the same way as outlined above in "Adding a new language". Your translations can be split over several files, since the `translations` config object can take a glob, e.g.:
+
+```ts
+translations: {
+  de: path.join(__dirname, 'ui-extensions/my-extension/**/*.de.json'),
+}
+```
+
+This allows you, if you wish, to co-locate your translation files with your components.
+
+Care should be taken to uniquely namespace your translation tokens, as conflicts with the base translation file will cause your translations to overwrite the defaults. This can be solved by using a unique section name, e.g.:
+
+```JSON
+{
+  "my-reviews-plugin": {
+    "all-reviews": "All reviews",
+    "approve review": "Approve review"
+  }
+}
+```

package/docs/guides/extending-the-admin-ui/admin-ui-theming-branding/index.md

@@ -0,0 +1,133 @@
+---
+title: 'Admin UI Theming & Branding'
+---
+
+The Vendure Admin UI can be themed to your company's style and branding.
+    
+## AdminUiPlugin branding settings
+
+The `AdminUiPlugin` allows you to specify your "brand" name, and allows you to control whether to display the Vendure name and version in the UI. Specifying a brand name will also set it as the title of the Admin UI in the browser.
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        AdminUiPlugin.init({
+            // ...
+            adminUiConfig:{
+                brand: 'My Store',
+                hideVendureBranding: false,
+                hideVersion: false,
+            }
+        }),
+    ],
+};
+```
+
+:::note
+For the simple level of branding shown above, the `@vendure/ui-devkit` package is not required.
+:::
+
+## Specifying custom logos
+
+You can replace the Vendure logos and favicon with your own brand logo:
+
+1. Install `@vendure/ui-devkit`
+2. Configure the AdminUiPlugin to compile a custom build featuring your logos:
+    ```ts title="src/vendure-config.ts"
+    import path from 'path';
+    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+    import { VendureConfig } from '@vendure/core';
+    import { compileUiExtensions, setBranding } from '@vendure/ui-devkit/compiler';
+    
+    export const config: VendureConfig = {
+        // ...
+        plugins: [
+            AdminUiPlugin.init({
+                app: compileUiExtensions({
+                    outputPath: path.join(__dirname, '../admin-ui'),
+                    extensions: [
+                        setBranding({
+                            // The small logo appears in the top left of the screen  
+                            smallLogoPath: path.join(__dirname, 'images/my-logo-sm.png'),
+                            // The large logo is used on the login page  
+                            largeLogoPath: path.join(__dirname, 'images/my-logo-lg.png'),
+                            faviconPath: path.join(__dirname, 'images/my-favicon.ico'),
+                        }),
+                    ],
+                }),
+            }),
+        ],
+    }
+    ```
+
+## Theming
+
+Much of the visual styling of the Admin UI can be customized by providing your own themes in a Sass stylesheet. For the most part, the Admin UI uses [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) to control colors and other styles. Here's a simple example which changes the color of links:
+
+1. Install `@vendure/ui-devkit`
+2. Create a custom stylesheet which overrides one or more of the CSS custom properties used in the Admin UI:
+    ```css title="my-theme.scss"
+    :root {
+      --clr-link-active-color: hsl(110, 65%, 57%);
+      --clr-link-color: hsl(110, 65%, 57%);
+      --clr-link-hover-color: hsl(110, 65%, 57%);
+      --clr-link-visited-color: hsl(110, 55%, 75%);
+    }
+    ```
+   To get an idea of which custom properties are available for theming, take a look at the source of the [Default theme](https://github.com/vendurehq/vendure/tree/master/packages/admin-ui/src/lib/static/styles/theme/default.scss) and the [Dark theme](https://github.com/vendurehq/vendure/tree/master/packages/admin-ui/src/lib/static/styles/theme/dark.scss)
+3. Set this as a globalStyles extension:   
+    ```ts title="src/vendure-config.ts"
+    import path from 'path';
+    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+    import { VendureConfig } from '@vendure/core';
+    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+    
+    export const config: VendureConfig = {
+        // ...
+        plugins: [
+            AdminUiPlugin.init({
+                app: compileUiExtensions({
+                    outputPath: path.join(__dirname, '../admin-ui'),
+                    extensions: [{
+                        globalStyles: path.join(__dirname, 'my-theme.scss')
+                    }],
+                }),
+            }),
+        ],
+    }
+    ```
+
+Some customizable styles in [Clarity](https://clarity.design/), the Admin UI's underlying UI framework, are controlled by Sass variables, which can be found on the [project's GitHub page](https://github.com/vmware-clarity/ng-clarity/blob/689a572344149aea90df1676eae04479795754f3/projects/angular/src/utils/_variables.clarity.scss). Similar to above, you can also provide your own values, which will override defaults set by the framework. Here's an example which changes the [height of the main header](https://github.com/vmware-clarity/ng-clarity/blob/689a572344149aea90df1676eae04479795754f3/projects/angular/src/layout/main-container/_variables.header.scss#L10):
+
+1. Install `@vendure/ui-devkit` if not already installed
+2. Create a custom stylesheet which overrides the target variable(s):
+    ```css title="my-variables.scss"
+    $clr-header-height: 4rem;
+    ```
+3. Set this as a `sassVariableOverrides` extension:
+    ```ts title="src/vendure-config.ts"
+    import path from 'path';
+    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+    import { VendureConfig } from '@vendure/core';
+    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+
+    export const config: VendureConfig = {
+        // ...
+        plugins: [
+            AdminUiPlugin.init({
+                app: compileUiExtensions({
+                    outputPath: path.join(__dirname, 'admin-ui'),
+                    extensions: [{
+                        sassVariableOverrides: path.join(__dirname, 'my-variables.scss')
+                    }],
+                }),
+            }),
+        ],
+    }
+    ```
+
+`globalStyles` and `sassVariableOverrides` extensions can be used in conjunction or separately.

package/docs/guides/extending-the-admin-ui/alerts/index.md

@@ -0,0 +1,56 @@
+---
+title: 'Alerts'
+---
+
+Alerts appear in the top bar of the Admin UI and provide a way of notifying the administrator of important information
+that may require action.
+
+You can define custom alerts with the [`registerAlert` function](/reference/admin-ui-api/alerts/register-alert/).
+
+Let's say you have a custom order process where certain orders require manual review & approval. You could define an
+alert to notify the administrator when there are orders that require review:
+
+```ts title="src/plugins/manual-order-review/ui/providers.ts"
+import { registerAlert } from '@vendure/admin-ui/core';
+import { Router } from '@angular/router';
+import { interval } from 'rxjs';
+
+import { ManualOrderReviewService } from './providers/manual-order-review.service';
+
+export default [
+    ManualOrderReviewService,
+    registerAlert({
+        id: 'orders-require-approval',
+        // This function is responsible for fetching the data needed to determine
+        // whether the alert should be displayed.
+        check: ({ injector }) => {
+            const manualOrderReviewService = injector.get(ManualOrderReviewService);
+            return manualOrderReviewService.getOrdersRequiringApproval()
+                .then(orders => orders.length);
+        },
+        // This function is responsible for determining whether and how often the
+        // `check` function should be called. In this case, we will check every 60 seconds.
+        recheck: () => interval(60_000),
+        // This function gets passed the data returned by the `check` function and
+        // should return `true` if the alert should be displayed.
+        isAlert: orderCount => orderCount > 0,
+        // This function is called when the alert is clicked. Here, we will navigate to
+        // a new route to display the orders requiring approval.
+        action: (orderCount, { injector }) => {
+            injector.get(Router).navigate(['/extensions/manual-order-review']);
+        },
+        // This function is called to determine the label of the alert.
+        label: (orderCount) => ({
+            text: `${orderCount} ${orderCount === 1 ? 'order' : 'orders'} require approval`,
+        }),
+    }),
+];
+```
+
+With this example, a check will be performed every 60 seconds to see if there are any orders requiring approval. The actual
+implementation of the check is left to the `ManualOrderReviewService` which in this case would make a request to the 
+Vendure server to fetch the required data.
+
+If there are orders requiring approval, the alert will appear in the Admin UI like this:
+
+![Alerts](./alerts-01.webp)

package/docs/guides/extending-the-admin-ui/bulk-actions/index.md

@@ -0,0 +1,78 @@
+---
+title: 'Bulk Actions for List Views'
+---
+
+List views in the Admin UI support bulk actions, which are performed on any selected items in the list. There are a default set of bulk actions that are defined by the Admin UI itself (e.g. delete, assign to channels), but using the `@vendure/ui-devit` package you are also able to define your own bulk actions.
+
+![./bulk-actions-screenshot.webp](./bulk-actions-screenshot.webp)
+
+Use cases for bulk actions include things like:
+
+- Sending multiple products to a 3rd-party localization service
+- Exporting selected products to csv
+- Bulk-updating custom field data
+
+### Bulk Action Example
+
+Bulk actions are declared using the [`registerBulkAction` function](/reference/admin-ui-api/bulk-actions/register-bulk-action/)
+
+```ts title="src/plugins/translation/ui/providers.ts"
+import { ModalService, registerBulkAction } from '@vendure/admin-ui/core';
+import { ProductDataTranslationService } from './product-data-translation.service';
+
+export default [
+    ProductDataTranslationService,
+    // Here is where we define our bulk action
+    // for sending the selected products to a 3rd-party
+    // translation API
+    registerBulkAction({
+        // This tells the Admin UI that this bulk action should be made
+        // available on the product list view.
+        location: 'product-list',
+        label: 'Send to translation service',
+        icon: 'language',
+        // Here is the logic that is executed when the bulk action menu item
+        // is clicked.
+        onClick: ({injector, selection}) => {
+            const modalService = injector.get(ModalService);
+            const translationService = injector.get(ProductDataTranslationService);
+            modalService
+                .dialog({
+                    title: `Send ${selection.length} products for translation?`,
+                    buttons: [
+                        {type: 'secondary', label: 'cancel'},
+                        {type: 'primary', label: 'send', returnValue: true},
+                    ],
+                })
+                .subscribe(response => {
+                    if (response) {
+                        translationService.sendForTranslation(selection.map(item => item.productId));
+                    }
+                });
+        },
+    }),
+];
+```
+
+### Conditionally displaying bulk actions
+
+Sometimes a bulk action only makes sense in certain circumstances. For example, the "assign to channel" action only makes sense when your server has multiple channels set up.
+
+We can conditionally control the display of a bulk action with the `isVisible` function, which should return a Promise resolving to a boolean:
+
+```ts title="src/plugins/my-plugin/ui/providers.ts"
+import { registerBulkAction, DataService } from '@vendure/admin-ui/core';
+
+export default [
+    registerBulkAction({
+        location: 'product-list',
+        label: 'Assign to channel',
+        // Only display this action if there are multiple channels
+        isVisible: ({ injector }) => injector.get(DataService).client
+            .userStatus()
+            .mapSingle(({ userStatus }) => 1 < userStatus.channels.length)
+            .toPromise(),
+        // ...
+    }),
+];
+```