@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

package/README.md

@@ -1,13 +1,112 @@
 # Vendure Dashboard
 
-This is an admin dashboard for managing Vendure applications. It is designed to supersede the existing Admin UI.
+This is a React-based admin dashboard for Vendure. It is a standalone application that can be extended to suit the
+needs of any Vendure project.
 
-Current status: early work in progress
+The package consists of three main components:
+
+- `@vendure/dashboard`: Dashboard source code
+- `@vendure/dashboard/vite`: A Vite plugin that is used to compile the dashboard in your project
+- `@vendure/dashboard/plugin`: A Vendure plugin that provides backend functionality used by the dashboard app.
+
+## DashboardPlugin
+
+### Basic usage - serving the Dashboard UI
+
+```typescript
+import { DashboardPlugin } from '@vendure/dashboard-plugin';
+
+const config: VendureConfig = {
+  // Add an instance of the plugin to the plugins array
+  plugins: [
+    DashboardPlugin.init({ route: 'dashboard' }),
+  ],
+};
+```
+
+The Dashboard UI will be served at the `/dashboard/` path.
+
+### Using only the metrics API
+
+If you are building a stand-alone version of the Dashboard UI app and don't need this plugin to serve the Dashboard UI, you can still use the `metricSummary` query by adding the `DashboardPlugin` to the `plugins` array without calling the `init()` method:
+
+```typescript
+import { DashboardPlugin } from '@vendure/dashboard-plugin';
+
+const config: VendureConfig = {
+  plugins: [
+    DashboardPlugin, // <-- no call to .init()
+  ],
+  // ...
+};
+```
+
+### Custom Dashboard UI build
+
+You can also provide a custom build of the Dashboard UI:
+
+```typescript
+import { DashboardPlugin } from '@vendure/dashboard-plugin';
+
+const config: VendureConfig = {
+  plugins: [
+    DashboardPlugin.init({ 
+      route: 'dashboard',
+      app: path.join(__dirname, 'custom-dashboard-build'),
+    }),
+  ],
+};
+```
+
+## API
+
+### DashboardPluginOptions
+
+- `route: string` - The route at which the Dashboard UI will be served (default: `'dashboard'`)
+- `app?: string` - Optional path to a custom build of the Dashboard UI
 
 ## Development
 
 Run `npx vite` to start Vite in dev mode.
 
+### Note on internal `@/vdb` imports
+
+You will notice that the dashboard uses internal Vendure Dashboard imports prefixed with `@/vdb`. This is adapted from the
+convention of Shadcn which uses a `@/*` path alias for internal imports.
+
+**Why not just use relative imports?**
+
+The problem with using relative imports is that they are handled differently by Vite when compiling the dashboard. This
+manifests as things like React Context not working correctly. The underlying reason is that Vite will selectively
+pre-compile source code and mixing the imports between alias and relative can result in 2 "versions" of the same code
+being loaded, which causes issues with React Context and other things that rely on a single instance of a module.
+
+For this reason, try to use the `@/vdb` alias for all internal Vendure Dashboard imports to the "src/lib" directory.
+
+This is especially import for hooks (since many of them use React Context) and there is even a pre-commit hook
+that will run [a script](./scripts/check-internal-imports.js) to ensure that you are not using relative imports for
+internal Vendure Dashboard code.
+
+**Type Safety for Consumers**
+
+Because we ship source code in the npm package, consumers need to tell TypeScript how to resolve these internal
+imports by adding the path alias to _their_ `tsconfig.json` file.
+
+```json
+{
+    "compilerOptions": {
+        "paths": {
+            "@/vdb/*": [
+                "./node_modules/@vendure/dashboard/src/lib/*"
+            ]
+        }
+    }
+}
+```
+
+Note: even without that path alias, the vite compilation will still work, but TypeScript types will not resolve correctly
+when developing dashboard extensions.
+
 ## Testing
 
-Run `npm run test` to run tests once, or `npx vitest` to run tests in watch mode
+Run `npm run test` to run tests once, or `npx vitest` to run tests in watch mode

package/dist/plugin/api/api-extensions.d.ts

@@ -0,0 +1 @@
+export declare const adminApiExtensions: import("graphql").DocumentNode;

package/dist/plugin/api/api-extensions.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adminApiExtensions = void 0;
+const graphql_tag_1 = __importDefault(require("graphql-tag"));
+exports.adminApiExtensions = (0, graphql_tag_1.default) `
+    type MetricSummary {
+        interval: MetricInterval!
+        type: MetricType!
+        title: String!
+        entries: [MetricSummaryEntry!]!
+    }
+    enum MetricInterval {
+        Daily
+    }
+    enum MetricType {
+        OrderCount
+        OrderTotal
+        AverageOrderValue
+    }
+    type MetricSummaryEntry {
+        label: String!
+        value: Float!
+    }
+    input MetricSummaryInput {
+        interval: MetricInterval!
+        types: [MetricType!]!
+        refresh: Boolean
+    }
+    extend type Query {
+        """
+        Get metrics for the given interval and metric types.
+        """
+        metricSummary(input: MetricSummaryInput): [MetricSummary!]!
+    }
+`;

package/dist/plugin/api/metrics.resolver.d.ts

@@ -0,0 +1,8 @@
+import { RequestContext } from '@vendure/core';
+import { MetricsService } from '../service/metrics.service.js';
+import { MetricSummary, MetricSummaryInput } from '../types.js';
+export declare class MetricsResolver {
+    private service;
+    constructor(service: MetricsService);
+    metricSummary(ctx: RequestContext, input: MetricSummaryInput): Promise<MetricSummary[]>;
+}

package/dist/plugin/api/metrics.resolver.js

@@ -0,0 +1,40 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsResolver = void 0;
+const graphql_1 = require("@nestjs/graphql");
+const core_1 = require("@vendure/core");
+const metrics_service_js_1 = require("../service/metrics.service.js");
+let MetricsResolver = class MetricsResolver {
+    constructor(service) {
+        this.service = service;
+    }
+    async metricSummary(ctx, input) {
+        return this.service.getMetrics(ctx, input);
+    }
+};
+exports.MetricsResolver = MetricsResolver;
+__decorate([
+    (0, graphql_1.Query)(),
+    (0, core_1.Allow)(core_1.Permission.ReadOrder),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, graphql_1.Args)('input')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, Object]),
+    __metadata("design:returntype", Promise)
+], MetricsResolver.prototype, "metricSummary", null);
+exports.MetricsResolver = MetricsResolver = __decorate([
+    (0, graphql_1.Resolver)(),
+    __metadata("design:paramtypes", [metrics_service_js_1.MetricsService])
+], MetricsResolver);

package/dist/plugin/config/metrics-strategies.d.ts

@@ -0,0 +1,39 @@
+import { RequestContext } from '@vendure/core';
+import { MetricData } from '../service/metrics.service.js';
+import { MetricInterval, MetricSummaryEntry, MetricType } from '../types.js';
+/**
+ * Calculate your metric data based on the given input.
+ * Be careful with heavy queries and calculations,
+ * as this function is executed everytime a user views its dashboard
+ *
+ */
+export interface MetricCalculation {
+    type: MetricType;
+    getTitle(ctx: RequestContext): string;
+    calculateEntry(ctx: RequestContext, interval: MetricInterval, data: MetricData): MetricSummaryEntry;
+}
+export declare function getMonthName(monthNr: number): string;
+/**
+ * Calculates the average order value per month/week
+ */
+export declare class AverageOrderValueMetric implements MetricCalculation {
+    readonly type = MetricType.AverageOrderValue;
+    getTitle(ctx: RequestContext): string;
+    calculateEntry(ctx: RequestContext, interval: MetricInterval, data: MetricData): MetricSummaryEntry;
+}
+/**
+ * Calculates number of orders
+ */
+export declare class OrderCountMetric implements MetricCalculation {
+    readonly type = MetricType.OrderCount;
+    getTitle(ctx: RequestContext): string;
+    calculateEntry(ctx: RequestContext, interval: MetricInterval, data: MetricData): MetricSummaryEntry;
+}
+/**
+ * Calculates order total
+ */
+export declare class OrderTotalMetric implements MetricCalculation {
+    readonly type = MetricType.OrderTotal;
+    getTitle(ctx: RequestContext): string;
+    calculateEntry(ctx: RequestContext, interval: MetricInterval, data: MetricData): MetricSummaryEntry;
+}

package/dist/plugin/config/metrics-strategies.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderTotalMetric = exports.OrderCountMetric = exports.AverageOrderValueMetric = void 0;
+exports.getMonthName = getMonthName;
+const types_js_1 = require("../types.js");
+function getMonthName(monthNr) {
+    const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    return monthNames[monthNr];
+}
+/**
+ * Calculates the average order value per month/week
+ */
+class AverageOrderValueMetric {
+    constructor() {
+        this.type = types_js_1.MetricType.AverageOrderValue;
+    }
+    getTitle(ctx) {
+        return 'average-order-value';
+    }
+    calculateEntry(ctx, interval, data) {
+        const label = data.date.toISOString();
+        if (!data.orders.length) {
+            return {
+                label,
+                value: 0,
+            };
+        }
+        const total = data.orders.map(o => o.totalWithTax).reduce((_total, current) => _total + current);
+        const average = Math.round(total / data.orders.length);
+        return {
+            label,
+            value: average,
+        };
+    }
+}
+exports.AverageOrderValueMetric = AverageOrderValueMetric;
+/**
+ * Calculates number of orders
+ */
+class OrderCountMetric {
+    constructor() {
+        this.type = types_js_1.MetricType.OrderCount;
+    }
+    getTitle(ctx) {
+        return 'order-count';
+    }
+    calculateEntry(ctx, interval, data) {
+        const label = data.date.toISOString();
+        return {
+            label,
+            value: data.orders.length,
+        };
+    }
+}
+exports.OrderCountMetric = OrderCountMetric;
+/**
+ * Calculates order total
+ */
+class OrderTotalMetric {
+    constructor() {
+        this.type = types_js_1.MetricType.OrderTotal;
+    }
+    getTitle(ctx) {
+        return 'order-totals';
+    }
+    calculateEntry(ctx, interval, data) {
+        const label = data.date.toISOString();
+        return {
+            label,
+            value: data.orders.map(o => o.totalWithTax).reduce((_total, current) => _total + current, 0),
+        };
+    }
+}
+exports.OrderTotalMetric = OrderTotalMetric;

package/dist/plugin/constants.d.ts

@@ -1,5 +1,6 @@
-import { LanguageCode } from '@vendure/core';
-export declare const defaultLanguage = LanguageCode.en;
+export declare const DEFAULT_APP_PATH: string;
+export declare const loggerCtx = "DashboardPlugin";
+export declare const defaultLanguage = "en";
 export declare const defaultLocale: undefined;
-export declare const defaultAvailableLanguages: LanguageCode[];
+export declare const defaultAvailableLanguages: string[];
 export declare const defaultAvailableLocales: string[];

package/dist/plugin/constants.js

@@ -1,277 +1,10 @@
-import { LanguageCode } from '@vendure/core';
-export const defaultLanguage = LanguageCode.en;
-export const defaultLocale = undefined;
-export const defaultAvailableLanguages = [
-    LanguageCode.he,
-    LanguageCode.ar,
-    LanguageCode.de,
-    LanguageCode.en,
-    LanguageCode.es,
-    LanguageCode.pl,
-    LanguageCode.zh_Hans,
-    LanguageCode.zh_Hant,
-    LanguageCode.pt_BR,
-    LanguageCode.pt_PT,
-    LanguageCode.cs,
-    LanguageCode.fr,
-    LanguageCode.ru,
-    LanguageCode.uk,
-    LanguageCode.it,
-    LanguageCode.fa,
-    LanguageCode.ne,
-    LanguageCode.hr,
-    LanguageCode.sv,
-    LanguageCode.nb,
-    LanguageCode.tr,
-];
-export const defaultAvailableLocales = [
-    'AF',
-    'AL',
-    'DZ',
-    'AS',
-    'AD',
-    'AO',
-    'AI',
-    'AQ',
-    'AG',
-    'AR',
-    'AM',
-    'AW',
-    'AU',
-    'AT',
-    'AZ',
-    'BS',
-    'BH',
-    'BD',
-    'BB',
-    'BY',
-    'BE',
-    'BZ',
-    'BJ',
-    'BM',
-    'BT',
-    'BO',
-    'BQ',
-    'BA',
-    'BW',
-    'BV',
-    'BR',
-    'IO',
-    'BN',
-    'BG',
-    'BF',
-    'BI',
-    'CV',
-    'KH',
-    'CM',
-    'CA',
-    'KY',
-    'CF',
-    'TD',
-    'CL',
-    'CN',
-    'CX',
-    'CC',
-    'CO',
-    'KM',
-    'CD',
-    'CG',
-    'CK',
-    'CR',
-    'HR',
-    'CU',
-    'CW',
-    'CY',
-    'CZ',
-    'CI',
-    'DK',
-    'DJ',
-    'DM',
-    'DO',
-    'EC',
-    'EG',
-    'SV',
-    'GQ',
-    'ER',
-    'EE',
-    'SZ',
-    'ET',
-    'FK',
-    'FO',
-    'FJ',
-    'FI',
-    'FR',
-    'GF',
-    'PF',
-    'TF',
-    'GA',
-    'GM',
-    'GE',
-    'DE',
-    'GH',
-    'GI',
-    'GR',
-    'GL',
-    'GD',
-    'GP',
-    'GU',
-    'GT',
-    'GG',
-    'GN',
-    'GW',
-    'GY',
-    'HT',
-    'HM',
-    'VA',
-    'HN',
-    'HK',
-    'HU',
-    'IS',
-    'IN',
-    'ID',
-    'IR',
-    'IQ',
-    'IE',
-    'IM',
-    'IL',
-    'IT',
-    'JM',
-    'JP',
-    'JE',
-    'JO',
-    'KZ',
-    'KE',
-    'KI',
-    'KP',
-    'KR',
-    'KW',
-    'KG',
-    'LA',
-    'LV',
-    'LB',
-    'LS',
-    'LR',
-    'LY',
-    'LI',
-    'LT',
-    'LU',
-    'MO',
-    'MG',
-    'MW',
-    'MY',
-    'MV',
-    'ML',
-    'MT',
-    'MH',
-    'MQ',
-    'MR',
-    'MU',
-    'YT',
-    'MX',
-    'FM',
-    'MD',
-    'MC',
-    'MN',
-    'ME',
-    'MS',
-    'MA',
-    'MZ',
-    'MM',
-    'NA',
-    'NR',
-    'NP',
-    'NL',
-    'NC',
-    'NZ',
-    'NI',
-    'NE',
-    'NG',
-    'NU',
-    'NF',
-    'MK',
-    'MP',
-    'NO',
-    'OM',
-    'PK',
-    'PW',
-    'PS',
-    'PA',
-    'PG',
-    'PY',
-    'PE',
-    'PH',
-    'PN',
-    'PL',
-    'PT',
-    'PR',
-    'QA',
-    'RO',
-    'RU',
-    'RW',
-    'RE',
-    'BL',
-    'SH',
-    'KN',
-    'LC',
-    'MF',
-    'PM',
-    'VC',
-    'WS',
-    'SM',
-    'ST',
-    'SA',
-    'SN',
-    'RS',
-    'SC',
-    'SL',
-    'SG',
-    'SX',
-    'SK',
-    'SI',
-    'SB',
-    'SO',
-    'ZA',
-    'GS',
-    'SS',
-    'ES',
-    'LK',
-    'SD',
-    'SR',
-    'SJ',
-    'SE',
-    'CH',
-    'SY',
-    'TW',
-    'TJ',
-    'TZ',
-    'TH',
-    'TL',
-    'TG',
-    'TK',
-    'TO',
-    'TT',
-    'TN',
-    'TR',
-    'TM',
-    'TC',
-    'TV',
-    'UG',
-    'UA',
-    'AE',
-    'GB',
-    'UM',
-    'US',
-    'UY',
-    'UZ',
-    'VU',
-    'VE',
-    'VN',
-    'VG',
-    'VI',
-    'WF',
-    'EH',
-    'YE',
-    'ZM',
-    'ZW',
-    'AX',
-];
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultAvailableLocales = exports.defaultAvailableLanguages = exports.defaultLocale = exports.defaultLanguage = exports.loggerCtx = exports.DEFAULT_APP_PATH = void 0;
+const path_1 = require("path");
+exports.DEFAULT_APP_PATH = (0, path_1.join)(__dirname, 'dist');
+exports.loggerCtx = 'DashboardPlugin';
+exports.defaultLanguage = 'en';
+exports.defaultLocale = undefined;
+exports.defaultAvailableLanguages = ['en', 'de', 'es', 'cs', 'zh_Hans', 'pt_BR', 'pt_PT', 'zh_Hant'];
+exports.defaultAvailableLocales = ['en-US', 'de-DE', 'es-ES', 'zh-CN', 'zh-TW', 'pt-BR', 'pt-PT'];