@ngbplatform/ui 1.3.0

package/src/ngb/editor/useRouteQueryEditorDrawer.ts

@@ -0,0 +1,173 @@
+import { computed, getCurrentInstance, inject } from 'vue';
+import {
+  matchedRouteKey,
+  onBeforeRouteUpdate,
+  type LocationQuery,
+  type RouteLocationNormalizedLoaded,
+  type Router,
+} from 'vue-router';
+
+import type { Awaitable } from '../metadata/types';
+import {
+  normalizeSingleQueryValue,
+  pushCleanRouteQuery,
+  replaceCleanRouteQuery,
+} from '../router/queryParams';
+
+export type RouteQueryEditorDrawerMode = 'new' | 'edit' | null;
+
+export type RouteQueryEditorDrawerState = {
+  mode: RouteQueryEditorDrawerMode;
+  id: string | null;
+};
+
+export type RouteQueryEditorDrawerOpenState = {
+  mode: 'new' | 'edit';
+  id: string | null;
+};
+
+export type RouteQueryEditorDrawerMutationOptions = {
+  patch?: Record<string, unknown>;
+  onCommit?: () => void;
+};
+
+export type UseRouteQueryEditorDrawerArgs = {
+  route: RouteLocationNormalizedLoaded;
+  router: Router;
+  panelKey?: string;
+  idKey?: string;
+  clearKeys?: string[];
+  idImpliesEdit?: boolean;
+  onBeforeOpen?: (
+    next: RouteQueryEditorDrawerOpenState,
+    current: RouteQueryEditorDrawerState,
+  ) => Awaitable<boolean>;
+  onBeforeClose?: (
+    current: RouteQueryEditorDrawerState,
+    next: RouteQueryEditorDrawerState,
+  ) => Awaitable<boolean>;
+};
+
+export function useRouteQueryEditorDrawer(args: UseRouteQueryEditorDrawerArgs) {
+  const panelKey = args.panelKey ?? 'panel';
+  const idKey = args.idKey ?? 'id';
+  const clearKeys = args.clearKeys ?? [];
+  let suppressedRouteGuards = 0;
+
+  function resolveState(query: LocationQuery): RouteQueryEditorDrawerState {
+    const id = normalizeSingleQueryValue(query[idKey]) || null;
+    const panel = normalizeSingleQueryValue(query[panelKey]).toLowerCase();
+    if (panel === 'new') return { mode: 'new', id: null };
+    if (panel === 'edit' && id) return { mode: 'edit', id };
+    if (args.idImpliesEdit && id) return { mode: 'edit', id };
+    return { mode: null, id: null };
+  }
+
+  function sameState(left: RouteQueryEditorDrawerState, right: RouteQueryEditorDrawerState) {
+    return left.mode === right.mode && left.id === right.id;
+  }
+
+  const panelState = computed(() => resolveState(args.route.query));
+  const panelId = computed(() => panelState.value.id);
+  const panelMode = computed<RouteQueryEditorDrawerMode>(() => panelState.value.mode);
+  const currentId = computed(() => (panelMode.value === 'edit' ? panelId.value : null));
+  const isPanelOpen = computed(() => panelMode.value !== null);
+
+  function currentState(): RouteQueryEditorDrawerState {
+    return panelState.value;
+  }
+
+  async function commitRouteMutation(run: () => Promise<unknown>) {
+    suppressedRouteGuards += 1;
+    try {
+      await run();
+    } finally {
+      suppressedRouteGuards = Math.max(0, suppressedRouteGuards - 1);
+    }
+  }
+
+  function buildPatch(
+    mode: RouteQueryEditorDrawerMode,
+    id: string | null,
+    patch?: Record<string, unknown>,
+  ) {
+    const nextPatch: Record<string, unknown> = {};
+    for (const key of clearKeys) nextPatch[key] = undefined;
+    nextPatch[panelKey] = mode ?? undefined;
+    nextPatch[idKey] = mode === 'edit' ? id ?? undefined : undefined;
+    return {
+      ...nextPatch,
+      ...(patch ?? {}),
+    };
+  }
+
+  async function openCreateDrawer(options: RouteQueryEditorDrawerMutationOptions = {}): Promise<boolean> {
+    const current = currentState();
+    if (current.mode === 'new') return false;
+
+    const next: RouteQueryEditorDrawerOpenState = { mode: 'new', id: null };
+    if (await args.onBeforeOpen?.(next, current) === false) return false;
+
+    options.onCommit?.();
+    await commitRouteMutation(async () => {
+      await pushCleanRouteQuery(args.route, args.router, buildPatch('new', null, options.patch));
+    });
+    return true;
+  }
+
+  async function openEditDrawer(
+    id: string,
+    options: RouteQueryEditorDrawerMutationOptions = {},
+  ): Promise<boolean> {
+    const normalizedId = String(id ?? '').trim();
+    if (!normalizedId) return false;
+
+    const current = currentState();
+    if (current.mode === 'edit' && current.id === normalizedId) return false;
+
+    const next: RouteQueryEditorDrawerOpenState = { mode: 'edit', id: normalizedId };
+    if (await args.onBeforeOpen?.(next, current) === false) return false;
+
+    options.onCommit?.();
+    await commitRouteMutation(async () => {
+      await pushCleanRouteQuery(args.route, args.router, buildPatch('edit', normalizedId, options.patch));
+    });
+    return true;
+  }
+
+  async function closeDrawer(options: RouteQueryEditorDrawerMutationOptions = {}): Promise<void> {
+    options.onCommit?.();
+    await commitRouteMutation(async () => {
+      await replaceCleanRouteQuery(args.route, args.router, buildPatch(null, null, options.patch));
+    });
+  }
+
+  const activeMatchedRoute = getCurrentInstance() ? inject(matchedRouteKey, null) : null;
+
+  if (activeMatchedRoute) {
+    onBeforeRouteUpdate(async (to) => {
+      if (suppressedRouteGuards > 0) return true;
+
+      const current = currentState();
+      const next = resolveState(to.query);
+      if (sameState(current, next)) return true;
+
+      if (next.mode === null) {
+        if (current.mode === null) return true;
+        return await args.onBeforeClose?.(current, next) !== false;
+      }
+
+      return await args.onBeforeOpen?.(next, current) !== false;
+    });
+  }
+
+  return {
+    panelId,
+    panelMode,
+    currentId,
+    isPanelOpen,
+    openCreateDrawer,
+    openEditDrawer,
+    closeDrawer,
+  };
+}

package/src/ngb/env/runtimeConfig.ts

@@ -0,0 +1,25 @@
+type RuntimeConfigValue = string | boolean | number | null | undefined
+
+declare global {
+  interface Window {
+    __NGB_RUNTIME_CONFIG__?: Record<string, RuntimeConfigValue>
+  }
+}
+
+function readWindowRuntimeConfig(): Record<string, RuntimeConfigValue> | null {
+  if (typeof window === 'undefined') return null
+
+  const runtimeConfig = window.__NGB_RUNTIME_CONFIG__
+  if (!runtimeConfig || typeof runtimeConfig !== 'object') return null
+
+  return runtimeConfig
+}
+
+export function readAppEnv(name: string): string {
+  const runtimeConfig = readWindowRuntimeConfig()
+  if (runtimeConfig && Object.prototype.hasOwnProperty.call(runtimeConfig, name)) {
+    return String(runtimeConfig[name] ?? '').trim()
+  }
+
+  return String(import.meta.env[name as keyof ImportMetaEnv] ?? '').trim()
+}

package/src/ngb/lookup/config.ts

@@ -0,0 +1,42 @@
+import type { Awaitable, LookupItem } from '../metadata/types'
+
+export type LookupSearchOptions = {
+  filters?: Record<string, string>
+}
+
+export type ResolvedDocumentLookupItem = LookupItem & {
+  documentType: string
+}
+
+export type LookupFrameworkConfig = {
+  loadCatalogItemsByIds: (catalogType: string, ids: string[]) => Awaitable<LookupItem[]>
+  searchCatalog: (catalogType: string, query: string, options?: LookupSearchOptions) => Awaitable<LookupItem[]>
+  loadCoaItem: (id: string) => Awaitable<LookupItem | null>
+  loadCoaItemsByIds: (ids: string[]) => Awaitable<LookupItem[]>
+  searchCoa: (query: string) => Awaitable<LookupItem[]>
+  loadDocumentItem: (documentType: string, id: string) => Awaitable<LookupItem | null>
+  loadDocumentItemsByIds: (documentTypes: string[], ids: string[]) => Awaitable<ResolvedDocumentLookupItem[]>
+  searchDocument: (documentType: string, query: string) => Awaitable<LookupItem[]>
+  searchDocumentsAcrossTypes: (documentTypes: string[], query: string) => Awaitable<ResolvedDocumentLookupItem[]>
+  buildCatalogUrl: (catalogType: string, id: string) => string
+  buildCoaUrl: (id: string) => string
+  buildDocumentUrl: (documentType: string, id: string) => string
+}
+
+let lookupFrameworkConfig: LookupFrameworkConfig | null = null
+
+export function configureNgbLookup(config: LookupFrameworkConfig): void {
+  lookupFrameworkConfig = config
+}
+
+export function getConfiguredNgbLookup(): LookupFrameworkConfig {
+  if (!lookupFrameworkConfig) {
+    throw new Error('NGB lookup framework is not configured. Call configureNgbLookup(...) during app bootstrap.')
+  }
+
+  return lookupFrameworkConfig
+}
+
+export function maybeGetConfiguredNgbLookup(): LookupFrameworkConfig | null {
+  return lookupFrameworkConfig
+}

package/src/ngb/lookup/defaultConfig.ts

@@ -0,0 +1,136 @@
+import type {
+  DocumentLookupDto,
+  LookupItemDto,
+} from '../api/contracts'
+import { getCatalogPage } from '../api/catalogs'
+import {
+  getDocumentById,
+  getDocumentLookupByIds,
+  getDocumentPage,
+  lookupDocumentsAcrossTypes,
+} from '../api/documents'
+import { getCatalogLookupByIds, lookupCatalog } from '../api/lookups'
+import {
+  getChartOfAccountById,
+  getChartOfAccountsByIds,
+  getChartOfAccountsPage,
+} from '../accounting/api'
+import { buildChartOfAccountsPath } from '../accounting/navigation'
+import { buildCatalogFullPageUrl } from '../editor/catalogNavigation'
+import { buildDocumentFullPageUrl } from '../editor/documentNavigation'
+import type { LookupItem } from '../metadata/types'
+import { shortGuid } from '../utils/guid'
+import type { LookupFrameworkConfig, ResolvedDocumentLookupItem } from './config'
+
+function toMetaString(meta: LookupItemDto['meta'] | string | undefined | null): string | undefined {
+  if (!meta) return undefined
+  if (typeof meta === 'string') return meta
+  if (typeof meta === 'object') {
+    const pairs = Object.entries(meta)
+      .slice(0, 4)
+      .map(([key, value]) => `${key}: ${String(value)}`)
+    return pairs.length > 0 ? pairs.join(' · ') : undefined
+  }
+  return String(meta)
+}
+
+function asLookupItem(item: { id: string; label: string; meta?: string | undefined }): LookupItem {
+  return {
+    id: item.id,
+    label: item.label,
+    meta: item.meta,
+  }
+}
+
+function asResolvedDocumentLookupItem(item: DocumentLookupDto): ResolvedDocumentLookupItem {
+  const label = String(item.display ?? '').trim() || shortGuid(item.id)
+  return {
+    id: item.id,
+    label,
+    documentType: item.documentType,
+  }
+}
+
+function mapLookupItemDto(item: LookupItemDto): LookupItem {
+  return asLookupItem({
+    id: item.id,
+    label: item.label,
+    meta: toMetaString(item.meta),
+  })
+}
+
+export function createDefaultNgbLookupConfig(): LookupFrameworkConfig {
+  return {
+    loadCatalogItemsByIds: async (catalogType, ids) => (await getCatalogLookupByIds(catalogType, ids)).map(mapLookupItemDto),
+    searchCatalog: async (catalogType, query, options) => {
+      const filters = options?.filters ?? null
+
+      if (!filters || Object.keys(filters).length === 0) {
+        return (await lookupCatalog(catalogType, query, 25)).map(mapLookupItemDto)
+      }
+
+      const page = await getCatalogPage(catalogType, {
+        offset: 0,
+        limit: 25,
+        search: query,
+        filters: {
+          deleted: 'active',
+          ...filters,
+        },
+      })
+
+      return (page.items ?? []).map((item) =>
+        asLookupItem({
+          id: item.id,
+          label: item.display ?? shortGuid(item.id),
+        }))
+    },
+    loadCoaItemsByIds: async (ids) => (await getChartOfAccountsByIds(ids)).map(mapLookupItemDto),
+    loadCoaItem: async (id) => {
+      const account = await getChartOfAccountById(id)
+      return asLookupItem({
+        id: account.accountId,
+        label: `${account.code} — ${account.name}`,
+      })
+    },
+    searchCoa: async (query) => {
+      const page = await getChartOfAccountsPage({ search: query, limit: 25, onlyActive: true, includeDeleted: false })
+      return (page.items ?? []).map((account) =>
+        asLookupItem({
+          id: account.accountId,
+          label: `${account.code} — ${account.name}`,
+        }))
+    },
+    loadDocumentItemsByIds: async (documentTypes, ids) => {
+      if (documentTypes.length === 0 || ids.length === 0) return []
+      return (await getDocumentLookupByIds({ documentTypes, ids })).map(asResolvedDocumentLookupItem)
+    },
+    searchDocumentsAcrossTypes: async (documentTypes, query) => {
+      if (documentTypes.length === 0) return []
+      return (await lookupDocumentsAcrossTypes({
+        documentTypes,
+        query,
+        perTypeLimit: 25,
+        activeOnly: true,
+      })).map(asResolvedDocumentLookupItem)
+    },
+    loadDocumentItem: async (documentType, id) => {
+      const document = await getDocumentById(documentType, id)
+      return asLookupItem({
+        id: document.id,
+        label: document.display ?? shortGuid(document.id),
+      })
+    },
+    searchDocument: async (documentType, query) => {
+      const page = await getDocumentPage(documentType, { offset: 0, limit: 25, search: query })
+      return (page.items ?? []).map((document) =>
+        asLookupItem({
+          id: document.id,
+          label: document.display ?? shortGuid(document.id),
+        }))
+    },
+    buildCatalogUrl: (catalogType, id) => buildCatalogFullPageUrl(catalogType, id),
+    buildCoaUrl: (id) => buildChartOfAccountsPath({ panel: 'edit', id }),
+    buildDocumentUrl: (documentType, id) => buildDocumentFullPageUrl(documentType, id),
+  }
+}

package/src/ngb/lookup/navigation.ts

@@ -0,0 +1,76 @@
+import { currentRouteBackTarget, withBackTarget } from '../router/backNavigation'
+import type { LookupHint, LookupSource } from '../metadata/types'
+import { getConfiguredNgbLookup } from './config'
+
+export type LookupValueLike =
+  | string
+  | {
+      id?: string | null
+    }
+  | null
+  | undefined
+
+export type LookupNavigationSource = LookupHint | LookupSource
+
+export function lookupValueId(value: LookupValueLike): string | null {
+  if (!value) return null
+
+  if (typeof value === 'string') {
+    const normalized = value.trim()
+    return normalized.length > 0 ? normalized : null
+  }
+
+  const normalized = String(value.id ?? '').trim()
+  return normalized.length > 0 ? normalized : null
+}
+
+async function resolveDocumentType(documentTypes: string[], id: string): Promise<string | null> {
+  const candidates = Array.from(new Set(documentTypes.map((entry) => String(entry ?? '').trim()).filter((entry) => entry.length > 0)))
+  if (candidates.length === 0) return null
+  if (candidates.length === 1) return candidates[0] ?? null
+
+  const config = getConfiguredNgbLookup()
+
+  try {
+    const items = await config.loadDocumentItemsByIds(candidates, [id])
+    const resolved = items.find((item) => {
+      const itemId = String(item.id ?? '').trim()
+      const documentType = String(item.documentType ?? '').trim()
+      return itemId === id && candidates.includes(documentType)
+    })
+
+    const resolvedType = String(resolved?.documentType ?? '').trim()
+    return resolvedType.length > 0 ? resolvedType : null
+  } catch {
+    return null
+  }
+}
+
+export async function buildLookupFieldTargetUrl(args: {
+  hint: LookupNavigationSource | null
+  value: LookupValueLike
+  route: {
+    fullPath: string
+  }
+}): Promise<string | null> {
+  const id = lookupValueId(args.value)
+  const hint = args.hint
+
+  if (!id || !hint) return null
+
+  const config = getConfiguredNgbLookup()
+  let path: string | null = null
+
+  if (hint.kind === 'catalog') {
+    path = config.buildCatalogUrl(hint.catalogType, id)
+  } else if (hint.kind === 'coa') {
+    path = config.buildCoaUrl(id)
+  } else if (hint.kind === 'document') {
+    const documentType = await resolveDocumentType(hint.documentTypes, id)
+    if (!documentType) return null
+    path = config.buildDocumentUrl(documentType, id)
+  }
+
+  if (!path) return null
+  return withBackTarget(path, currentRouteBackTarget(args.route))
+}

package/src/ngb/lookup/prefetch.ts

@@ -0,0 +1,40 @@
+import { ensureResolvedLookupLabels } from '../metadata/filtering'
+import type { LookupHint, LookupSource, LookupStoreApi, RecordFields } from '../metadata/types'
+import { isNonEmptyGuid } from '../utils/guid'
+
+type LookupPrefetchColumn = {
+  key: string
+  lookup?: LookupSource | null
+}
+
+type LookupPrefetchItem = {
+  payload?: {
+    fields?: RecordFields | null
+  } | null
+}
+
+export async function prefetchLookupsForPage(args: {
+  entityTypeCode: string
+  columns: readonly LookupPrefetchColumn[]
+  items: readonly LookupPrefetchItem[]
+  lookupStore: LookupStoreApi
+  resolveLookupHint: (entityTypeCode: string, fieldKey: string, lookup?: LookupSource | null) => LookupHint | null
+}) {
+  const tasks: Promise<void>[] = []
+
+  for (const column of args.columns) {
+    const hint = args.resolveLookupHint(args.entityTypeCode, column.key, column.lookup)
+    if (!hint) continue
+
+    const ids = args.items
+      .map((item) => item.payload?.fields?.[column.key])
+      .filter(isNonEmptyGuid)
+
+    if (ids.length === 0) continue
+    tasks.push(Promise.resolve().then(() => ensureResolvedLookupLabels(args.lookupStore, hint, ids)))
+  }
+
+  if (tasks.length > 0) {
+    await Promise.allSettled(tasks)
+  }
+}