@myparcel-dev/pdk-admin 1.13.0

package/src/composables/formatter/useLocalizedFormatter.ts

@@ -0,0 +1,11 @@
+import {useLanguage} from '../language';
+import {useGlobalContext} from '../context';
+import {useFormatter} from './useFormatter';
+import {type Formatter} from './formatter.types';
+
+export const useLocalizedFormatter = (): Formatter => {
+  const globalContext = useGlobalContext();
+  const {translate} = useLanguage();
+
+  return useFormatter(globalContext.language, translate);
+};

package/src/composables/index.ts

@@ -0,0 +1,17 @@
+export * from './components';
+export * from './context';
+export * from './formatter';
+export * from './language';
+export * from './orders';
+export * from './products';
+export * from './shipments';
+export * from './useAdminConfig';
+export * from './useAdminInstance';
+export * from './useDigitalStampRanges';
+export * from './useGlobalPdkAdmin';
+export * from './useLoadMore';
+export * from './useLoading';
+export * from './useLogger';
+export * from './useStoreContextQuery';
+export * from './useStoreQuery';
+export * from './useWeekdays';

package/src/composables/language/index.ts

@@ -0,0 +1,4 @@
+export * from './resolveTranslatedString';
+export * from './resolveTranslationKey';
+export * from './types';
+export * from './useLanguage';

package/src/composables/language/resolveTranslatedString.ts

@@ -0,0 +1,30 @@
+import {get} from 'lodash-unified';
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {useGlobalContext} from '../context';
+import {type Translatable} from '../../types';
+import {type Replacers} from './types';
+
+export const resolveTranslatedString = (
+  translated: string,
+  replacers: undefined | Replacers,
+  translation: string | Translatable,
+): string => {
+  const matches = translated.match(/\{[\w.]+}/g);
+
+  if (!matches) {
+    return translated;
+  }
+
+  const resolvedReplacers = {
+    ...useGlobalContext(),
+    ...(isOfType<Translatable>(translation, 'args') && translation.args),
+    ...replacers,
+  };
+
+  return matches.reduce((acc, match) => {
+    const replacerKey = match.substring(1, match.length - 1).trim();
+    const replacement = get(resolvedReplacers, replacerKey, '');
+
+    return acc.replace(match, String(replacement));
+  }, translated);
+};

package/src/composables/language/resolveTranslationKey.ts

@@ -0,0 +1,5 @@
+import {type Translatable} from '../../types';
+
+export const resolveTranslationKey = (translation: string | Translatable): string => {
+  return typeof translation === 'string' ? translation : translation.key;
+};

package/src/composables/language/types.ts

@@ -0,0 +1 @@
+export type Replacers = Record<string, unknown | Record<string, unknown>>;

package/src/composables/language/useLanguage.spec.ts

@@ -0,0 +1,124 @@
+// @vitest-environment happy-dom
+
+import {afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, type MockInstance, vi} from 'vitest';
+import {mount} from '@vue/test-utils';
+import {useQueryStore} from '../../stores';
+import {globalLogger} from '../../services';
+import {doComponentTestSetup, doComponentTestTeardown, mockDefaultTranslations} from '../../__tests__';
+import {useLanguage} from './useLanguage';
+
+let warnSpy: MockInstance;
+
+const commonSetup = () => {
+  useQueryStore().registerContextQueries();
+
+  return useLanguage();
+};
+
+describe('useLanguage', () => {
+  beforeAll(() => {
+    mockDefaultTranslations.mockReturnValue({
+      my_translation: 'My translation',
+      my_translation_with_replacement: 'My translation with replacement: {platform.backofficeUrl}',
+      translation_with_custom_replacer: '{platform.name} said {word}',
+    });
+  });
+
+  beforeEach(() => {
+    doComponentTestSetup();
+
+    warnSpy = vi.spyOn(globalLogger, 'warn');
+  });
+
+  afterEach(() => {
+    warnSpy.mockClear();
+    doComponentTestTeardown();
+  });
+
+  afterAll(() => {
+    mockDefaultTranslations.mockReset();
+  });
+
+  describe('translate', () => {
+    it('translates strings', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ translate("my_translation") }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('My translation');
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('warns about missing translations', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ translate("missing") }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('missing');
+      expect(warnSpy).toHaveBeenCalledWith('Missing translation: missing');
+    });
+
+    it('translates strings with replacements', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ translate("my_translation_with_replacement") }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe(
+        'My translation with replacement: https://backoffice.test.myparcel.nl',
+      );
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('handles non-translatables', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ translate({text: "plain text"}) }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('plain text');
+    });
+
+    it('translates translatables', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ translate({key: "translation_with_custom_replacer", args: {word: "wow" } }) }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('test said wow');
+    });
+  });
+
+  describe('has', () => {
+    it('returns true for existing translations', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ has("my_translation") }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('true');
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('returns false for missing translations', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ has("missing") }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('false');
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('returns true for non-translatables', () => {
+      const wrapper = mount({
+        setup: commonSetup,
+        template: '<div>{{ has({text: "plain text"}) }}</div>',
+      });
+
+      expect(wrapper.find('div').element.innerText).toBe('true');
+    });
+  });
+});

package/src/composables/language/useLanguage.ts

@@ -0,0 +1,117 @@
+import {type Ref, ref} from 'vue';
+import {createGlobalState, useMemoize} from '@vueuse/core';
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {useGlobalContext} from '../context';
+import {decodeHtmlEntities} from '../../utils';
+import {type NonTranslatable, type Translatable, type Translation} from '../../types';
+import {globalLogger} from '../../services';
+import {type Replacers} from './types';
+import {resolveTranslationKey} from './resolveTranslationKey';
+import {resolveTranslatedString} from './resolveTranslatedString';
+
+type UseLanguage = {
+  /**
+   * A list of all invalid keys that were passed to translate().
+   */
+  missingKeys: Ref<string[]>;
+
+  /**
+   * Get all translations.
+   */
+  all(): Record<string, string>;
+
+  /**
+   * Check if a given translation key exists.
+   */
+  has(key: Translation | undefined): boolean;
+
+  /**
+   * Translate a string into the current language.
+   */
+  translate(key?: Translation, replacers?: Replacers): string;
+};
+
+/**
+ * Cached translations.
+ */
+const useCache = createGlobalState<() => Map<string, string>>(() => new Map());
+
+/**
+ * Keys that are missing in the translation file.
+ */
+const useMissingKeys = createGlobalState<() => Ref<string[]>>(() => ref([]));
+
+const all: UseLanguage['all'] = () => {
+  const {translations} = useGlobalContext();
+
+  if (!translations) {
+    globalLogger.warn('Translations not found.');
+  }
+
+  return translations;
+};
+
+const has: UseLanguage['has'] = (translation) => {
+  if (!translation) {
+    return false;
+  }
+
+  if (isOfType<NonTranslatable>(translation, 'text')) {
+    return true;
+  }
+
+  const translations = memoizedAll();
+
+  return Boolean(translation && translations && resolveTranslationKey(translation) in translations);
+};
+
+const translate: UseLanguage['translate'] = (translation, replacers) => {
+  if (!translation) {
+    return '';
+  }
+
+  if (isOfType<NonTranslatable>(translation, 'text')) {
+    return translation.text;
+  }
+
+  const translationKey = resolveTranslationKey(translation);
+
+  const cache = useCache();
+
+  const cacheKey = [translationKey, isOfType<Translatable>(translation, 'args') ? translation.args : undefined]
+    .filter(Boolean)
+    .join('|');
+
+  if (memoizedHas(translation)) {
+    if (!cache.has(cacheKey)) {
+      const translations = memoizedAll();
+      const translated = decodeHtmlEntities(translations[translationKey]);
+
+      cache.set(cacheKey, resolveTranslatedString(translated, replacers, translation));
+    }
+  } else {
+    const missingKeys = useMissingKeys();
+    // eslint-disable-next-line no-console
+    globalLogger.warn(`Missing translation: ${translationKey}`);
+    missingKeys.value.push(translationKey);
+    cache.set(cacheKey, translationKey);
+  }
+
+  return cache.get(cacheKey) as string;
+};
+
+const memoizedAll = useMemoize(all);
+const memoizedHas = useMemoize(has);
+const memoizedTranslate = useMemoize(translate);
+
+export const useLanguage = (): UseLanguage => {
+  const missingKeys = useMissingKeys();
+
+  return {
+    missingKeys,
+
+    all: memoizedAll,
+    has: memoizedHas,
+    translate: memoizedTranslate,
+  };
+};

package/src/composables/orders/index.ts

@@ -0,0 +1,3 @@
+export * from './useOrder';
+export * from './useOrderData';
+export * from './useOrdersData';

package/src/composables/orders/useOrder.ts

@@ -0,0 +1,8 @@
+import {BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {useStoreQuery} from '../useStoreQuery';
+import {getOrderId, validateId} from '../../utils';
+import {type ResolvedQuery} from '../../stores';
+
+export const useOrder = (externalIdentifier?: string): ResolvedQuery<BackendEndpoint.FetchOrders> => {
+  return useStoreQuery(BackendEndpoint.FetchOrders, validateId(externalIdentifier ?? getOrderId()));
+};

package/src/composables/orders/useOrderData.ts

@@ -0,0 +1,29 @@
+import {computed, type ComputedRef, toValue} from 'vue';
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {getOrderId, validateId} from '../../utils';
+import {type ResolvedQuery, useQueryStore} from '../../stores';
+import {useOrder} from './useOrder';
+
+export interface UseOrderData {
+  loading: ComputedRef<boolean>;
+  order: ComputedRef;
+  query: ResolvedQuery<BackendEndpoint.FetchOrders>;
+}
+
+export const useOrderData = (externalIdentifier?: string): UseOrderData => {
+  const orderId = validateId(externalIdentifier ?? getOrderId());
+
+  const queryStore = useQueryStore();
+
+  const fetchQuery = useOrder(orderId);
+
+  const allQueries = queryStore.getQueriesForOrder(orderId);
+
+  return {
+    loading: computed(() => {
+      return Object.values(toValue(allQueries)).some((item) => (item ? toValue(item.isLoading) : false));
+    }),
+    order: computed(() => toValue(fetchQuery.data)),
+    query: fetchQuery,
+  };
+};

package/src/composables/orders/useOrdersData.ts

@@ -0,0 +1,14 @@
+import {type OneOrMore, toArray} from '@myparcel-dev/ts-utils';
+import {getOrderId, validateId} from '../../utils';
+import {type UseOrderData, useOrderData} from './useOrderData';
+
+export const useOrdersData = (externalIdentifiers?: OneOrMore<string>): UseOrderData[] => {
+  try {
+    const orderIds = validateId(externalIdentifiers ?? getOrderId(), true);
+    return toArray(orderIds).map((externalIdentifier) => useOrderData(externalIdentifier));
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(error);
+    return [];
+  }
+};

package/src/composables/products/index.ts

@@ -0,0 +1 @@
+export * from './useProductData';

package/src/composables/products/useProductData.ts

@@ -0,0 +1,23 @@
+import {computed, type ComputedRef, toValue} from 'vue';
+import {BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {useStoreQuery} from '../useStoreQuery';
+import {useInstanceContext} from '../context';
+import {validateId} from '../../utils';
+import {type ResolvedQuery} from '../../stores';
+import {AdminInstanceContextKey} from '../../data';
+
+export interface UseProductData {
+  product: ComputedRef;
+  query: ResolvedQuery<BackendEndpoint.FetchProducts>;
+}
+
+export const useProductData = (externalIdentifier?: string): UseProductData => {
+  const productId = validateId(externalIdentifier ?? useInstanceContext(AdminInstanceContextKey.ProductIdentifier));
+
+  const fetchQuery = useStoreQuery(BackendEndpoint.FetchProducts, productId);
+
+  return {
+    product: computed(() => toValue(fetchQuery.data)),
+    query: fetchQuery,
+  };
+};

package/src/composables/shipments/index.ts

@@ -0,0 +1,3 @@
+export * from './useShipment';
+export * from './useShipmentData';
+export * from './useShipmentsData';

package/src/composables/shipments/useShipment.ts

@@ -0,0 +1,7 @@
+import {BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {useStoreQuery} from '../useStoreQuery';
+import {type ResolvedQuery} from '../../stores';
+
+export const useShipment = (id: number): ResolvedQuery<BackendEndpoint.FetchShipments> => {
+  return useStoreQuery(BackendEndpoint.FetchShipments, id.toString());
+};

package/src/composables/shipments/useShipmentData.ts

@@ -0,0 +1,52 @@
+import {computed, type ComputedRef, type Ref, ref, toValue, unref} from 'vue';
+import {type MaybeRef} from '@vueuse/core';
+import {type Shipment} from '@myparcel-dev/pdk-common';
+import {type Carrier} from '@myparcel-dev/sdk';
+import {type AnyActionDefinition} from '../../types';
+import {useQueryStore} from '../../stores';
+import {instantiateActions} from '../../services';
+import {useFetchCarrier} from '../../sdk';
+import {shipmentActions} from '../../actions';
+import {useShipment} from './useShipment';
+
+export type UseShipmentData = {
+  actions: AnyActionDefinition[];
+  carrier: Ref<Carrier | undefined>;
+  loading: Ref<boolean>;
+  shipment: ComputedRef<Shipment.ModelShipment>;
+};
+
+export const useShipmentData = (id: MaybeRef<number>): UseShipmentData => {
+  const shipmentId = unref(id);
+
+  const queryStore = useQueryStore();
+  const fetchQuery = useShipment(shipmentId);
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const shipment = computed(() => toValue(fetchQuery.data)!);
+
+  const orderId = toValue(shipment)?.orderId;
+
+  const allQueries = [
+    queryStore.getQueriesForShipment(shipmentId),
+    orderId ? queryStore.getQueriesForOrder(orderId) : undefined,
+  ].filter(Boolean);
+
+  const carrierName = shipment.value?.carrier?.name;
+  const carriersQuery = carrierName ? useFetchCarrier(carrierName) : undefined;
+
+  return {
+    actions: instantiateActions(shipmentActions, {
+      shipmentIds: shipment.value?.id,
+      orderIds: shipment.value?.orderId,
+    }),
+
+    carrier: carriersQuery?.data ?? ref(),
+    loading: computed(() => {
+      return allQueries.some((obj) =>
+        Object.values(toValue(obj) ?? {}).some((item) => (item ? toValue(item.isLoading) : false)),
+      );
+    }),
+    shipment,
+  };
+};

package/src/composables/shipments/useShipmentsData.ts

@@ -0,0 +1,5 @@
+import {type UseShipmentData, useShipmentData} from './useShipmentData';
+
+export const useShipmentsData = (ids: number[]): UseShipmentData[] => {
+  return ids.map((shipment) => useShipmentData(shipment));
+};

package/src/composables/useAdminConfig.ts

@@ -0,0 +1,8 @@
+import {type AdminConfiguration} from '../types';
+import {useAdminInstance} from './useAdminInstance';
+
+export const useAdminConfig = (): AdminConfiguration => {
+  const instance = useAdminInstance();
+
+  return instance.config;
+};

package/src/composables/useAdminInstance.ts

@@ -0,0 +1,13 @@
+import {inject} from 'vue';
+import {type AdminInstance} from '../types';
+import {INJECT_ADMIN_INSTANCE} from '../symbols';
+
+export const useAdminInstance = (): AdminInstance => {
+  const instance = inject(INJECT_ADMIN_INSTANCE);
+
+  if (!instance) {
+    throw new Error('No PDK instance found');
+  }
+
+  return instance;
+};

package/src/composables/useDigitalStampRanges.ts

@@ -0,0 +1,38 @@
+import {computed, type ComputedRef, toValue} from 'vue';
+import {type MaybeRef} from '@vueuse/core';
+import {type Plugin} from '@myparcel-dev/pdk-common';
+import {type SelectOptionWithPlainLabel} from '../types';
+import {useOrderData} from './orders';
+
+interface UseDigitalStampRanges {
+  ranges: ComputedRef<SelectOptionWithPlainLabel<number, string>[]>;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+  currentRange: ComputedRef<SelectOptionWithPlainLabel<number, string>>;
+}
+
+export const useDigitalStampRanges = (weight: MaybeRef<number>): UseDigitalStampRanges => {
+  // todo: move this to global context
+  const {order} = useOrderData();
+
+  const allRanges = computed<Plugin.DigitalStampRange[]>(() => toValue(order).digitalStampRanges ?? []);
+
+  const ranges = computed<SelectOptionWithPlainLabel<number, string>[]>(() => {
+    return allRanges.value.map((range) => ({
+      plainLabel: `${range.min}g – ${range.max}g`,
+      value: range.average,
+    }));
+  });
+
+  const currentRange = computed(() => {
+    const resolvedWeight = toValue(weight);
+
+    const matchingRange = allRanges.value.find((range) => range.min <= resolvedWeight && range.max >= resolvedWeight);
+
+    return ranges.value.find((range) => range.value === matchingRange?.average) ?? ranges.value[0];
+  });
+
+  return {
+    ranges,
+    currentRange,
+  };
+};

package/src/composables/useGlobalPdkAdmin.ts

@@ -0,0 +1,13 @@
+import {inject} from 'vue';
+import {INJECT_GLOBAL_PDK_ADMIN} from '../symbols';
+import {type PdkAdmin} from '../pdk';
+
+export const useGlobalPdkAdmin = (): PdkAdmin => {
+  const pdkAdmin = inject(INJECT_GLOBAL_PDK_ADMIN);
+
+  if (!pdkAdmin) {
+    throw new Error('PDK frontend not found. First use createPdkAdmin() to create the global instance.');
+  }
+
+  return pdkAdmin;
+};

package/src/composables/useLoadMore.spec.ts

@@ -0,0 +1,69 @@
+import {describe, expect, it} from 'vitest';
+import {useLoadMore} from '@myparcel-dev/do-shared';
+
+describe('useLoadMore', () => {
+  it('shows an initial set of items', () => {
+    const {items} = useLoadMore({
+      items: ['a', 'b', 'c'],
+    });
+
+    expect(items.value).toEqual(['a']);
+  });
+
+  it('shows a custom amount of initial items', () => {
+    const {items} = useLoadMore({
+      items: ['a', 'b', 'c'],
+      start: 2,
+    });
+
+    expect(items.value).toEqual(['a', 'b']);
+  });
+
+  it('can step through items', () => {
+    const {items, loadMore, hasMore, loaded} = useLoadMore({
+      items: ['a', 'b', 'c'],
+    });
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b']);
+    expect(hasMore.value).toBe(true);
+    expect(loaded.value).toBe(2);
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b', 'c']);
+    expect(hasMore.value).toBe(false);
+    expect(loaded.value).toBe(3);
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b', 'c']);
+    expect(hasMore.value).toBe(false);
+    expect(loaded.value).toBe(3);
+  });
+
+  it('can step through items with a custom step', () => {
+    const {items, loadMore, hasMore, loaded} = useLoadMore({
+      items: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'],
+      start: 1,
+      step: 3,
+    });
+
+    expect(items.value).toEqual(['a']);
+    expect(hasMore.value).toBe(true);
+    expect(loaded.value).toBe(1);
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b', 'c', 'd']);
+    expect(hasMore.value).toBe(true);
+    expect(loaded.value).toBe(4);
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b', 'c', 'd', 'e', 'f', 'g']);
+    expect(hasMore.value).toBe(true);
+    expect(loaded.value).toBe(7);
+
+    loadMore();
+    expect(items.value).toEqual(['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']);
+    expect(hasMore.value).toBe(false);
+    expect(loaded.value).toBe(9);
+  });
+});

package/src/composables/useLoadMore.ts

@@ -0,0 +1,46 @@
+import {computed, type ComputedRef, type MaybeRef, ref, type Ref, toValue} from 'vue';
+import {type ReadonlyOr} from '@myparcel-dev/ts-utils';
+
+export type UseLoadMoreOptions<Item = unknown> = {
+  step?: number;
+  start?: number;
+  items: ReadonlyOr<MaybeRef<Item[]>>;
+};
+
+export type UseLoadMore<Item = unknown> = {
+  loadMore(): void;
+  hasMore: ComputedRef<boolean>;
+  loaded: Ref<number>;
+  items: ComputedRef<Item[]>;
+};
+
+export const useLoadMore = <Item = unknown>(options: UseLoadMoreOptions<Item>): UseLoadMore<Item> => {
+  const loaded = ref(options.start ?? options.step ?? toValue(options.items).length - 1);
+
+  const hasMore = computed(() => loaded.value < toValue(options.items).length - 1);
+
+  const loadMore = () => {
+    if (!hasMore.value) {
+      return;
+    }
+
+    const step = options.step ?? 1;
+
+    const maxLength = toValue(options.items).length;
+
+    if (loaded.value + step > maxLength) {
+      loaded.value = maxLength;
+    } else {
+      loaded.value += step;
+    }
+  };
+
+  const items = computed(() => toValue(options.items).slice(0, loaded.value));
+
+  return {
+    items,
+    loaded,
+    hasMore,
+    loadMore,
+  };
+};