@myparcel-dev/pdk-admin 1.13.0

package/src/forms/shipmentOptions/fields/createReceiptCodeField.ts

@@ -0,0 +1,21 @@
+import {TriState} from '@myparcel-dev/pdk-common';
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {CarrierName} from '@myparcel-dev/constants';
+import {type ShipmentOptionsRefs} from '../types';
+import {FIELD_AGE_CHECK, FIELD_RECEIPT_CODE} from '../field';
+import {getFormCarrierName, hasPostNlAgeCheck} from '../../helpers';
+import {createShipmentOptionField} from './createShipmentOptionField';
+
+export const createReceiptCodeField = (refs: ShipmentOptionsRefs): InteractiveElementConfiguration => {
+  return createShipmentOptionField(refs, FIELD_RECEIPT_CODE, {
+    readOnlyWhen: ({form}) => hasPostNlAgeCheck(form),
+
+    afterUpdate({form}, value) {
+      if (!(CarrierName.DhlForYou === getFormCarrierName(form) && TriState.On === value)) {
+        return;
+      }
+
+      form.setValue(FIELD_AGE_CHECK, TriState.Off);
+    },
+  });
+};

package/src/forms/shipmentOptions/fields/createRef.ts

@@ -0,0 +1,6 @@
+import {ref, type Ref, type UnwrapRef} from 'vue';
+import {type ShipmentOptionsRefs} from '../types';
+
+export const createRef = <T>(refs: ShipmentOptionsRefs, field: string, fallback?: T): Ref<UnwrapRef<T>> => {
+  return ref<T>((refs[field] ?? fallback) as T);
+};

package/src/forms/shipmentOptions/fields/createSameDayDeliveryField.ts

@@ -0,0 +1,8 @@
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ShipmentOptionsRefs} from '../types';
+import {FIELD_SAME_DAY_DELIVERY} from '../field';
+import {createShipmentOptionField} from './createShipmentOptionField';
+
+export const createSameDayDeliveryField = (refs: ShipmentOptionsRefs): InteractiveElementConfiguration => {
+  return createShipmentOptionField(refs, FIELD_SAME_DAY_DELIVERY);
+};

package/src/forms/shipmentOptions/fields/createShipmentOptionField.ts

@@ -0,0 +1,25 @@
+import {type Shipment, TriState} from '@myparcel-dev/pdk-common';
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ShipmentOptionsRefs} from '../types';
+import {type FieldName} from '../field';
+import {createHasShipmentOptionWatcher, defineFormField, getFieldLabel, resolveFormComponent} from '../../helpers';
+import {AdminComponent} from '../../../data';
+import {createRef} from './createRef';
+
+export const createShipmentOptionField = (
+  refs: ShipmentOptionsRefs,
+  fieldName: FieldName,
+  config?: Partial<InteractiveElementConfiguration>,
+): InteractiveElementConfiguration => {
+  const name = (fieldName.split('.').pop() ?? fieldName) as keyof Shipment.ModelShipmentOptions;
+
+  return defineFormField({
+    name: fieldName,
+    component: resolveFormComponent(AdminComponent.TriStateInput),
+    ref: createRef(refs, fieldName, TriState.Inherit),
+    label: getFieldLabel(name),
+    visibleWhen: createHasShipmentOptionWatcher(name),
+    disabledWhen: createHasShipmentOptionWatcher(name, true),
+    ...config,
+  });
+};

package/src/forms/shipmentOptions/fields/createSignatureField.ts

@@ -0,0 +1,11 @@
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ShipmentOptionsRefs} from '../types';
+import {FIELD_SIGNATURE} from '../field';
+import {hasPostNlAgeCheck} from '../../helpers';
+import {createShipmentOptionField} from './createShipmentOptionField';
+
+export const createSignatureField = (refs: ShipmentOptionsRefs): InteractiveElementConfiguration => {
+  return createShipmentOptionField(refs, FIELD_SIGNATURE, {
+    readOnlyWhen: ({form}) => hasPostNlAgeCheck(form),
+  });
+};

package/src/forms/shipmentOptions/fields/index.ts

@@ -0,0 +1,14 @@
+export * from './createAgeCheckField';
+export * from './createCarrierField';
+export * from './createDigitalStampRangeField';
+export * from './createDirectReturnField';
+export * from './createInsuranceField';
+export * from './createLabelAmountField';
+export * from './createLargeFormatField';
+export * from './createOnlyRecipientField';
+export * from './createPackageTypeField';
+export * from './createRef';
+export * from './createSameDayDeliveryField';
+export * from './createShipmentOptionField';
+export * from './createSignatureField';
+export * from './createReceiptCodeField';

package/src/forms/shipmentOptions/index.ts

@@ -0,0 +1,4 @@
+export * from './createShipmentOptionsForm';
+export * from './field';
+export * from './fields';
+export * from './types';

package/src/forms/shipmentOptions/types.ts

@@ -0,0 +1,3 @@
+import {type FieldName} from './field';
+
+export type ShipmentOptionsRefs = Record<FieldName, unknown>;

package/src/index.ts

@@ -0,0 +1,114 @@
+export type {
+  ComponentOrHtmlElement,
+  FieldConfiguration,
+  FieldConfiguration as AnyElementConfiguration,
+  FieldConfiguration as PlainElementConfiguration,
+  FieldConfiguration as ResolvedElementConfiguration,
+  FieldInstance,
+  FieldInstance as AnyElementInstance,
+  FieldInstance as PlainElementInstance,
+  FormConfiguration,
+  FormInstance,
+  InteractiveElementConfiguration,
+  InteractiveElementInstance,
+} from '@myparcel-dev/vue-form-builder';
+
+export * from './actions';
+export * from './deprecated';
+export * from './types';
+export * from './views/integrated';
+
+export * from '@myparcel-dev/pdk-common';
+
+export {
+  ActionButton,
+  BulkSelectCheckbox,
+  NotificationContainer,
+  PackageType,
+  PlainElement,
+  ResetButton,
+  ReturnsForm,
+  ShipmentBarcode,
+  ShipmentOptionsForm,
+  ShipmentStatus,
+  StatusIndicator,
+  SubmitButton,
+  TabNavigation,
+} from './components';
+
+export {
+  AdminAction,
+  AdminComponent,
+  AdminIcon,
+  AdminInstanceContextKey,
+  AdminModalKey,
+  AdminView,
+  NotificationCategory,
+  allAdminComponentNames,
+  optionalAdminActionContainerComponentNames,
+  optionalAdminComponentNames,
+  optionalAdminPlainWrapperComponentNames,
+  requiredAdminComponentNames,
+} from './data';
+
+export {
+  FORM_KEYS,
+  FORM_KEY_ACCOUNT_SETTINGS,
+  FORM_KEY_CHILD_PRODUCT_SETTINGS,
+  FORM_KEY_MODAL,
+  FORM_KEY_MODAL_PRINT_OPTIONS,
+  FORM_KEY_MODAL_RETURN_OPTIONS,
+  FORM_KEY_MODAL_SHIPMENT_OPTIONS,
+  FORM_KEY_PLUGIN_SETTINGS,
+  FORM_KEY_PRODUCT_SETTINGS,
+  resolveFormComponent,
+} from './forms';
+
+export {FormHook, useElement, useForm, useFormBuilder} from '@myparcel-dev/vue-form-builder';
+
+export {INJECT_ADMIN_INSTANCE, INJECT_GLOBAL_PDK_ADMIN} from './symbols';
+
+export {LogLevel, getActionIdentifier} from './services';
+
+export {PdkAdmin, createPdkAdmin} from './pdk';
+
+export {createAdminConfig, createPdkAdminPlugin} from './pdk';
+
+export {createFormElement} from './utils';
+
+export {createLogger} from './services';
+
+export {generateFieldId, prefixComponent} from './utils';
+
+export {useActionStore, useModalStore, useNotificationStore, useQueryStore} from './stores';
+
+export {
+  useAdminConfig,
+  useAppInfo,
+  useCheckboxGroupContext,
+  useDropOffInputContext,
+  useDropdownButtonContext,
+  useElementContext,
+  useElementOptions,
+  useFormatter,
+  useGlobalContext,
+  useGlobalPdkAdmin,
+  useInputWithOptionsContext,
+  useLanguage,
+  useLoadMore,
+  useLogger,
+  useModalContext,
+  useModalElementContext,
+  useMultiSelectInputContext,
+  useOrderData,
+  useOrdersData,
+  useProductData,
+  useRadioGroupContext,
+  useSelectInputContext,
+  useShippingMethodsInputContext,
+  useStoreQuery,
+  useTableContext,
+  useToggleInputContext,
+  useTriStateInputContext,
+  useWeekdays,
+} from './composables';

package/src/pdk/PdkAdmin.ts

@@ -0,0 +1,82 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+
+import {type App, createApp} from 'vue';
+import {type AdminAppConfig, type AdminConfiguration, type AdminContextObject} from '../types';
+import {INJECT_GLOBAL_PDK_ADMIN} from '../symbols';
+import {createLogger, getElementContext} from '../services';
+import {AdminView} from '../data';
+import {setupAdminApp} from './setupAdminApp';
+import {renderViewComponent} from './renderMap';
+
+export class PdkAdmin {
+  public readonly config: AdminConfiguration;
+  public readonly context: AdminContextObject;
+
+  public readonly renderedComponents: string[] = [];
+
+  public constructor(config: AdminConfiguration, context: AdminContextObject) {
+    config.beforeInitialize?.(config, context);
+
+    this.config = config;
+    this.context = context;
+
+    config.onInitialized?.(config, context);
+  }
+
+  /**
+   * Render a views in given selector.
+   */
+  public async render(view: AdminView, selector: string): Promise<void> {
+    const config: AdminConfiguration = {...this.config};
+    const context: AdminContextObject = {...this.context, ...getElementContext(selector)};
+
+    const appName = this.createAppName(view, context);
+    const logger = createLogger(appName);
+
+    logger.debug(`Rendering "${view}" in "${selector}"`);
+
+    const app = await this.createApp(view, {appName, config, context, logger, view});
+
+    try {
+      app.mount(selector);
+      this.renderedComponents.push(view);
+      config?.onRendered?.(config);
+      logger.debug(`Rendered in ${selector}`);
+    } catch (e) {
+      logger.error('Error mounting app', e);
+    }
+  }
+
+  protected async createApp(view: AdminView, appConfig: AdminAppConfig): Promise<App> {
+    appConfig.view = view;
+    appConfig.config?.beforeRender?.(appConfig.config);
+
+    const component = await renderViewComponent(view);
+    const app = createApp({...component, name: appConfig.appName}).provide(INJECT_GLOBAL_PDK_ADMIN, this);
+
+    setupAdminApp(app, appConfig);
+
+    return app;
+  }
+
+  /**
+   * Create a unique app name for components that are rendered multiple times.
+   */
+  protected createAppName(componentName: AdminView, context: AdminContextObject): string {
+    if (process.env.NODE_ENV === 'production') {
+      return componentName;
+    }
+
+    const {orderData} = context;
+
+    let appName: string = componentName;
+
+    if (componentName === AdminView.OrderListItem) {
+      const orderId = orderData?.length === 1 ? orderData[0].externalIdentifier : null;
+
+      appName += ` #${orderId}`;
+    }
+
+    return appName;
+  }
+}

package/src/pdk/boot.ts

@@ -0,0 +1,14 @@
+import {type AdminContextObject} from '../types';
+import {globalLogger} from '../services';
+import {sendBootEvent} from './sendBootEvent';
+import {type PdkAdmin} from './PdkAdmin';
+
+export const boot = (pdkAdmin: PdkAdmin, context: AdminContextObject): void => {
+  sendBootEvent(pdkAdmin, context);
+
+  document.addEventListener(context.global.eventPing, () => {
+    sendBootEvent(pdkAdmin, context);
+  });
+
+  globalLogger.debug('Created PDK admin!', {context});
+};

package/src/pdk/createAdminConfig.ts

@@ -0,0 +1,29 @@
+import {mergeWith} from 'lodash-unified';
+import {type AdminConfiguration, type DefaultAdminConfiguration, type InputAdminConfiguration} from '../types';
+import {LogLevel} from '../services';
+
+const createDefaultConfig = (): DefaultAdminConfiguration => ({
+  components: undefined,
+  formatters: {},
+  logLevel: import.meta.env.PROD ? LogLevel.Info : LogLevel.Debug,
+  transitions: {},
+  generateFieldId: (element) => `${element.form.name}-${element.name}`,
+});
+
+export const createAdminConfig = (customConfig?: InputAdminConfiguration | undefined): AdminConfiguration => {
+  const defaultConfig = createDefaultConfig();
+
+  const merged = mergeWith({}, defaultConfig, customConfig, (obj, src, key) => {
+    if (key === 'components') {
+      return src ?? obj;
+    }
+  });
+
+  Object.keys(defaultConfig).forEach((key) => {
+    if (!merged[key as keyof AdminConfiguration]) {
+      throw new Error(`Config key "${key}" is missing.`);
+    }
+  });
+
+  return Object.freeze(merged as unknown as AdminConfiguration);
+};

package/src/pdk/createPdkAdmin.ts

@@ -0,0 +1,39 @@
+import {type InputAdminConfiguration} from '../types';
+import {getElementContext, globalLogger} from '../services';
+import {createAdminConfig} from './createAdminConfig';
+import {boot} from './boot';
+import {PdkAdmin} from './PdkAdmin';
+
+export type CreatePdkAdmin = (configuration?: InputAdminConfiguration) => undefined | PdkAdmin;
+
+/**
+ * Must match \MyParcelNL\Pdk\Plugin\Service\Frontend::BOOTSTRAP_CONTAINER_ID.
+ *
+ * @see https://github.com/myparcelnl/pdk/blob/main/src/Frontend/Service/FrontendRenderService.php
+ */
+const BOOTSTRAP_CONTAINER_SELECTOR = '#myparcel-pdk-boot';
+
+/**
+ * Initialize the pdk frontend, parse configuration, and send a boot event that triggers the
+ * components to render themselves using the PdkAdmin class.
+ */
+export const createPdkAdmin: CreatePdkAdmin = (configuration?) => {
+  try {
+    const config = createAdminConfig(configuration);
+
+    globalLogger.level = config.logLevel;
+
+    const context = getElementContext(BOOTSTRAP_CONTAINER_SELECTOR);
+
+    const pdkAdmin = new PdkAdmin(config, context);
+
+    boot(pdkAdmin, context);
+
+    return pdkAdmin;
+  } catch (e) {
+    globalLogger.error('Failed to create PDK admin:');
+
+    // eslint-disable-next-line no-console
+    console.error(e);
+  }
+};

package/src/pdk/createPdkAdminPlugin.ts

@@ -0,0 +1,18 @@
+import {type Plugin} from 'vue';
+import {type AdminContextObject, type InputAdminConfiguration} from '../types';
+import {globalLogger} from '../services';
+import {setupAdminApp} from './setupAdminApp';
+import {createAdminConfig} from './createAdminConfig';
+
+export const createPdkAdminPlugin = (config: InputAdminConfiguration, context: AdminContextObject): Plugin => {
+  return {
+    install(app) {
+      setupAdminApp(app, {
+        appName: '',
+        config: createAdminConfig(config),
+        context,
+        logger: globalLogger,
+      });
+    },
+  };
+};

package/src/pdk/fillShipmentsQueryData.ts

@@ -0,0 +1,44 @@
+import {type QueryClient} from '@tanstack/vue-query';
+import {type Plugin, type Shipment} from '@myparcel-dev/pdk-common';
+import {type OneOrMore, toArray} from '@myparcel-dev/ts-utils';
+import {setQueryOrder, setQueryShipment} from '../utils';
+import {QUERY_KEY_ORDER} from '../actions';
+
+export const fillShipmentsQueryData = (
+  queryClient: QueryClient,
+  shipments: OneOrMore<Shipment.ModelShipment>,
+  order?: Plugin.ModelPdkOrder,
+): void => {
+  const shipmentsArray = toArray(shipments);
+  const orderIds = new Set(shipmentsArray.map((shipment) => shipment.orderId));
+
+  if (order) {
+    orderIds.add(order.externalIdentifier);
+  }
+
+  orderIds.forEach((orderId) => {
+    let newOrder = order;
+
+    if (!newOrder) {
+      const queryOrder = queryClient.getQueryData([QUERY_KEY_ORDER, {id: orderId}]) as Plugin.ModelPdkOrder;
+
+      if (!queryOrder) {
+        return;
+      }
+
+      newOrder = {
+        ...queryOrder,
+        shipments: queryOrder.shipments.map((shipment) => ({
+          ...shipment,
+          updated: shipmentsArray.find((item) => item.id === shipment.id)?.updated ?? shipment.updated,
+        })),
+      };
+    }
+
+    setQueryOrder(queryClient, newOrder);
+  });
+
+  shipmentsArray.forEach((shipment) => {
+    setQueryShipment(queryClient, shipment);
+  });
+};

package/src/pdk/index.ts

@@ -0,0 +1,11 @@
+export * from './PdkAdmin';
+export * from './boot';
+export * from './createAdminConfig';
+export * from './createPdkAdmin';
+export * from './createPdkAdminPlugin';
+export * from './fillShipmentsQueryData';
+export * from './instance';
+export * from './renderMap';
+export * from './sendBootEvent';
+export * from './setupAdminApp';
+export * from './testIdDirective';

package/src/pdk/instance/createInstanceContext.ts

@@ -0,0 +1,23 @@
+import {type AdminContextObject, type AdminInstanceContext} from '../../types';
+import {AdminInstanceContextKey} from '../../data';
+
+/**
+ * Creates a context object for the current instance.
+ */
+export const createInstanceContext = (context: AdminContextObject): Partial<AdminInstanceContext> => {
+  const instanceContext: Partial<AdminInstanceContext> = {};
+
+  if (context.orderData?.length === 1) {
+    const [order] = context.orderData;
+
+    instanceContext[AdminInstanceContextKey.OrderIdentifier] = order.externalIdentifier;
+  }
+
+  if (context.productData?.length === 1) {
+    const [product] = context.productData;
+
+    instanceContext[AdminInstanceContextKey.ProductIdentifier] = product.externalIdentifier;
+  }
+
+  return instanceContext;
+};

package/src/pdk/instance/createQueryClient.ts

@@ -0,0 +1,31 @@
+import {QueryClient} from '@tanstack/vue-query';
+import {useNotificationStore} from '../../stores';
+import {addErrorToNotifications} from '../../services';
+import {NotificationCategory} from '../../data';
+
+const clearApiNotifications = () => {
+  useNotificationStore().remove(NotificationCategory.Api);
+};
+
+export const createQueryClient = (): QueryClient =>
+  new QueryClient({
+    defaultOptions: {
+      mutations: {
+        onMutate: clearApiNotifications,
+        retry: false,
+      },
+
+      queries: {
+        behavior: {
+          onFetch: clearApiNotifications,
+        },
+        refetchInterval: false,
+        refetchOnMount: false,
+        refetchOnReconnect: false,
+        refetchOnWindowFocus: false,
+        retry: false,
+        retryOnMount: false,
+        staleTime: Infinity,
+      },
+    },
+  });

package/src/pdk/instance/index.ts

@@ -0,0 +1,3 @@
+export * from './createInstanceContext';
+export * from './createQueryClient';
+export * from './plugins';

package/src/pdk/instance/plugins/createContextPlugin.ts

@@ -0,0 +1,17 @@
+import {createInstanceContext} from '../createInstanceContext';
+import {INJECT_ADMIN_INSTANCE} from '../../../symbols';
+import {type PdkAppPlugin} from './plugins.types';
+
+export const createContextPlugin: PdkAppPlugin = ({appName, config, context, logger, view}) => ({
+  install(app) {
+    logger.debug('Installing context plugin');
+
+    app.provide(INJECT_ADMIN_INSTANCE, {
+      appName,
+      config,
+      context: createInstanceContext(context),
+      logger,
+      view,
+    });
+  },
+});

package/src/pdk/instance/plugins/createLoggerPlugin.ts

@@ -0,0 +1,13 @@
+import {type PdkAppPlugin} from './plugins.types';
+
+export const createLoggerPlugin: PdkAppPlugin = (appConfig) => ({
+  install(app) {
+    app.config.errorHandler = (err: unknown): void => {
+      appConfig.logger.error(err);
+    };
+
+    app.config.warnHandler = (msg: string): void => {
+      appConfig.logger.warn(msg);
+    };
+  },
+});

package/src/pdk/instance/plugins/createRegisterComponentsPlugin.spec.ts

@@ -0,0 +1,58 @@
+/* eslint-disable max-nested-callbacks,@typescript-eslint/no-non-null-asserted-optional-chain */
+import {type App, type Component} from 'vue';
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {prefixComponent} from '../../../utils';
+import {type AdminComponentMap} from '../../../types';
+import {allAdminComponentNames, requiredAdminComponentNames} from '../../../data';
+import {mockDefaultAppConfig} from '../../../__tests__';
+import {createRegisterComponentsPlugin} from './createRegisterComponentsPlugin';
+
+describe('createRegisterComponentsPlugin', () => {
+  it.each([
+    ['with prefix', true],
+    ['without prefix', false],
+  ])('registers components %s', (_, withPrefix) => {
+    const registeredComponents: string[] = [];
+
+    mockDefaultAppConfig.mockImplementationOnce(() => {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const defaults = mockDefaultAppConfig.getMockImplementation()?.()!;
+
+      return {
+        ...defaults,
+        config: {
+          ...defaults?.config,
+          components: requiredAdminComponentNames.reduce((acc, name) => {
+            const resolvedName = withPrefix ? prefixComponent(name) : name;
+
+            return {
+              ...acc,
+              [resolvedName]: {} as Component,
+            };
+          }, {} as AdminComponentMap),
+        },
+      };
+    });
+
+    const app = {
+      component: vi.fn((name, component) => {
+        if (component) {
+          registeredComponents.push(name);
+          return {name};
+        }
+
+        return registeredComponents.includes(name) ? {name} : undefined;
+      }),
+      use: vi.fn(),
+    } as unknown as App;
+
+    const plugin = createRegisterComponentsPlugin(mockDefaultAppConfig());
+
+    expect(plugin).toHaveProperty('install');
+
+    plugin?.install?.(app);
+
+    expect(app.use).toHaveBeenCalledTimes(1);
+    expect(registeredComponents).toEqual(allAdminComponentNames.map(prefixComponent));
+  });
+});