@ngbplatform/ui 1.3.0

package/src/ngb/metadata/monthPagedListQuery.ts

@@ -0,0 +1,108 @@
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router'
+import { monthValueToDateOnly, normalizeMonthValue } from '../utils/dateValues'
+import { normalizeTrashMode, pushCleanRouteQuery, type QueryTrashMode } from '../router/queryParams'
+
+type UseMonthPagedListQueryArgs = {
+  route: RouteLocationNormalizedLoaded
+  router: Router
+  defaultLimit?: number
+}
+
+function parseNonNegativeInteger(value: unknown, fallback: number): number {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : fallback
+}
+
+function parsePositiveInteger(value: unknown, fallback: number): number {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback
+}
+
+export function monthValueToDateOnlyStart(monthValue: string): string | undefined {
+  return monthValueToDateOnly(monthValue) ?? undefined
+}
+
+export function monthValueToDateOnlyEnd(monthValue: string): string | undefined {
+  if (!/^\d{4}-\d{2}$/.test(monthValue)) return undefined
+
+  const [year, month] = monthValue.split('-').map((part) => Number(part))
+  if (!Number.isFinite(year) || !Number.isFinite(month)) return undefined
+
+  const lastDay = new Date(year, month, 0).getDate()
+  return `${monthValue}-${String(lastDay).padStart(2, '0')}`
+}
+
+export function useMonthPagedListQuery(args: UseMonthPagedListQueryArgs) {
+  const defaultLimit = args.defaultLimit ?? 50
+
+  const offset = computed(() => parseNonNegativeInteger(args.route.query.offset, 0))
+  const limit = computed(() => parsePositiveInteger(args.route.query.limit, defaultLimit))
+
+  function pushQuery(partial: Record<string, unknown>, options?: { preserveOffset?: boolean }) {
+    void pushCleanRouteQuery(args.route, args.router, {
+      ...partial,
+      ...(options?.preserveOffset ? {} : { offset: 0 }),
+    })
+  }
+
+  const trashMode = computed<QueryTrashMode>({
+    get() {
+      return normalizeTrashMode(args.route.query.trash)
+    },
+    set(value) {
+      pushQuery({ trash: value })
+    },
+  })
+
+  const periodFromMonth = computed<string>({
+    get() {
+      return normalizeMonthValue(args.route.query.periodFrom) ?? ''
+    },
+    set(value) {
+      pushQuery({ periodFrom: value || undefined })
+    },
+  })
+
+  const periodToMonth = computed<string>({
+    get() {
+      return normalizeMonthValue(args.route.query.periodTo) ?? ''
+    },
+    set(value) {
+      pushQuery({ periodTo: value || undefined })
+    },
+  })
+
+  function updateListQuery(partial: Record<string, unknown>, options?: { preserveOffset?: boolean }) {
+    pushQuery(partial, options)
+  }
+
+  function nextPage() {
+    pushQuery({ offset: offset.value + limit.value }, { preserveOffset: true })
+  }
+
+  function prevPage() {
+    pushQuery({ offset: Math.max(0, offset.value - limit.value) }, { preserveOffset: true })
+  }
+
+  return {
+    offset,
+    limit,
+    trashMode,
+    periodFromMonth,
+    periodToMonth,
+    updateListQuery,
+    nextPage,
+    prevPage,
+  } satisfies {
+    offset: ComputedRef<number>
+    limit: ComputedRef<number>
+    trashMode: ComputedRef<QueryTrashMode>
+    periodFromMonth: ComputedRef<string>
+    periodToMonth: ComputedRef<string>
+    updateListQuery: (partial: Record<string, unknown>, options?: { preserveOffset?: boolean }) => void
+    nextPage: () => void
+    prevPage: () => void
+  }
+}

package/src/ngb/metadata/normalization.ts

@@ -0,0 +1,100 @@
+import type {
+  CatalogTypeMetadata,
+  DocumentTypeMetadata,
+  FieldMetadata,
+  FormMetadata,
+  ListFilterField,
+  ListMetadata,
+  PartMetadata,
+} from './types'
+
+const DATA_TYPE_BY_LEGACY_CODE: Record<number, string> = {
+  1: 'String',
+  2: 'Int32',
+  3: 'Decimal',
+  4: 'Boolean',
+  5: 'Date',
+  6: 'DateTime',
+  7: 'Money',
+  8: 'Guid',
+}
+
+function normalizeDataType(value: unknown): string {
+  if (typeof value === 'string') {
+    const normalized = value.trim()
+    return normalized || 'Unknown'
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return DATA_TYPE_BY_LEGACY_CODE[Math.trunc(value)] ?? 'Unknown'
+  }
+
+  return 'Unknown'
+}
+
+function normalizeListFilterField(field: ListFilterField): ListFilterField {
+  return {
+    ...field,
+    dataType: normalizeDataType(field.dataType),
+  }
+}
+
+function normalizeListMetadata(list: ListMetadata | null | undefined): ListMetadata | null | undefined {
+  if (!list) return list
+
+  return {
+    ...list,
+    columns: (list.columns ?? []).map((column) => ({
+      ...column,
+      dataType: normalizeDataType(column.dataType),
+    })),
+    filters: (list.filters ?? []).map(normalizeListFilterField),
+  }
+}
+
+function normalizeField(field: FieldMetadata): FieldMetadata {
+  return {
+    ...field,
+    dataType: normalizeDataType(field.dataType),
+  }
+}
+
+function normalizeFormMetadata(form: FormMetadata | null | undefined): FormMetadata | null | undefined {
+  if (!form) return form
+
+  return {
+    ...form,
+    sections: (form.sections ?? []).map((section) => ({
+      ...section,
+      rows: (section.rows ?? []).map((row) => ({
+        ...row,
+        fields: (row.fields ?? []).map(normalizeField),
+      })),
+    })),
+  }
+}
+
+function normalizePartMetadata(part: PartMetadata): PartMetadata {
+  return {
+    ...part,
+    list: normalizeListMetadata(part.list) ?? part.list,
+  }
+}
+
+export function normalizeCatalogTypeMetadata(metadata: CatalogTypeMetadata): CatalogTypeMetadata {
+  return {
+    ...metadata,
+    list: normalizeListMetadata(metadata.list),
+    form: normalizeFormMetadata(metadata.form),
+    parts: (metadata.parts ?? []).map(normalizePartMetadata),
+  }
+}
+
+export function normalizeDocumentTypeMetadata(metadata: DocumentTypeMetadata): DocumentTypeMetadata {
+  return {
+    ...metadata,
+    list: normalizeListMetadata(metadata.list),
+    form: normalizeFormMetadata(metadata.form),
+    parts: (metadata.parts ?? []).map(normalizePartMetadata),
+  }
+}

package/src/ngb/metadata/referenceHydration.ts

@@ -0,0 +1,99 @@
+import { resolveNgbMetadataFormBehavior } from './config'
+import { isNonEmptyGuid } from '../utils/guid'
+import { flattenFormFields } from './entityForm'
+import { isReferenceValue } from './entityModel'
+import { resolveLookupHint } from './lookup'
+import type { EntityFormModel, FormMetadata, LookupHint, LookupStoreApi, MetadataFormBehavior, ReferenceValue } from './types'
+
+type PendingReferenceHydration = {
+  fieldKey: string
+  id: string
+  hint: LookupHint
+}
+
+function buildReferenceValue(id: string, display: string): ReferenceValue {
+  return {
+    id,
+    display: display.trim() || id,
+  }
+}
+
+function resolveReferenceLabel(lookupStore: LookupStoreApi, hint: LookupHint, id: string): string {
+  if (hint.kind === 'catalog') return lookupStore.labelForCatalog(hint.catalogType, id)
+  if (hint.kind === 'coa') return lookupStore.labelForCoa(id)
+  return lookupStore.labelForAnyDocument(hint.documentTypes, id)
+}
+
+export async function hydrateEntityReferenceFieldsForEditing(args: {
+  entityTypeCode: string
+  form: FormMetadata | null | undefined
+  model: EntityFormModel
+  lookupStore: LookupStoreApi
+  behavior?: MetadataFormBehavior
+}): Promise<void> {
+  const pending: PendingReferenceHydration[] = []
+  const behavior = resolveNgbMetadataFormBehavior(args.behavior)
+
+  for (const field of flattenFormFields(args.form)) {
+    const value = args.model[field.key]
+    if (isReferenceValue(value) || !isNonEmptyGuid(value)) continue
+
+    const hint = resolveLookupHint({
+      entityTypeCode: args.entityTypeCode,
+      model: args.model,
+      field,
+      behavior,
+    })
+
+    if (!hint) continue
+
+    pending.push({
+      fieldKey: field.key,
+      id: value,
+      hint,
+    })
+  }
+
+  if (pending.length === 0) return
+
+  const catalogIdsByType = new Map<string, Set<string>>()
+  const documentIdsByTypesKey = new Map<string, { documentTypes: string[]; ids: Set<string> }>()
+  const coaIds = new Set<string>()
+
+  for (const entry of pending) {
+    if (entry.hint.kind === 'catalog') {
+      const ids = catalogIdsByType.get(entry.hint.catalogType) ?? new Set<string>()
+      ids.add(entry.id)
+      catalogIdsByType.set(entry.hint.catalogType, ids)
+      continue
+    }
+
+    if (entry.hint.kind === 'coa') {
+      coaIds.add(entry.id)
+      continue
+    }
+
+    const key = entry.hint.documentTypes.join('|')
+    const group = documentIdsByTypesKey.get(key) ?? {
+      documentTypes: entry.hint.documentTypes,
+      ids: new Set<string>(),
+    }
+    group.ids.add(entry.id)
+    documentIdsByTypesKey.set(key, group)
+  }
+
+  const tasks: Promise<void>[] = []
+  for (const [catalogType, ids] of catalogIdsByType) {
+    tasks.push(args.lookupStore.ensureCatalogLabels(catalogType, [...ids]))
+  }
+  if (coaIds.size > 0) tasks.push(args.lookupStore.ensureCoaLabels([...coaIds]))
+  for (const group of documentIdsByTypesKey.values()) {
+    tasks.push(args.lookupStore.ensureAnyDocumentLabels(group.documentTypes, [...group.ids]))
+  }
+  await Promise.all(tasks)
+
+  for (const entry of pending) {
+    const display = resolveReferenceLabel(args.lookupStore, entry.hint, entry.id)
+    args.model[entry.fieldKey] = buildReferenceValue(entry.id, display)
+  }
+}

package/src/ngb/metadata/register.ts

@@ -0,0 +1,135 @@
+import type { ColumnMetadata, JsonValue, RecordFields } from './types'
+import type { RegisterColumn, RegisterDataRow } from '../components/register/registerTypes'
+import { dataTypeKind } from './dataTypes'
+import { isReferenceValue } from './entityModel'
+
+export type RegisterAlign = NonNullable<RegisterColumn['align']>
+export type RegisterRow = RegisterDataRow
+
+type RegisterRecordItem = {
+  id: string
+  payload?: {
+    fields?: RecordFields | null
+  } | null
+  isDeleted?: boolean
+  isMarkedForDeletion?: boolean
+  status?: unknown
+}
+
+type BuildColumnsArgs = {
+  columns: readonly ColumnMetadata[]
+  optionLabelsByColumnKey?: Record<string, Map<string, string>>
+  formatOverride?: (column: ColumnMetadata, value: unknown) => string | null
+}
+
+type BuildRowsArgs<TItem extends RegisterRecordItem> = {
+  items: readonly TItem[]
+  columns: readonly ColumnMetadata[]
+  mapFieldValue?: (column: ColumnMetadata, rawValue: JsonValue | undefined, item: TItem) => unknown
+  extendRow?: (row: RegisterRow, item: TItem) => void
+}
+
+const dateOnlyRe = /^\d{4}-\d{2}-\d{2}$/
+
+export function alignFromDto(value: unknown): RegisterAlign {
+  if (value === 2) return 'center'
+  if (value === 3) return 'right'
+  return 'left'
+}
+
+export function prettifyRegisterTitle(label: string, key: string): string {
+  const normalized = key.toLowerCase()
+  if (normalized.endsWith('_id') || normalized.endsWith('_account_id')) return label.replace(/\s+Id$/i, '')
+  return label
+}
+
+export function tryFormatDateOnly(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  if (!dateOnlyRe.test(value)) return null
+
+  const [year, month, day] = value.split('-').map((part) => Number(part))
+  if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day)) return null
+
+  const date = new Date(year, month - 1, day)
+  if (Number.isNaN(date.getTime())) return null
+  return date.toLocaleDateString()
+}
+
+export function formatRegisterValue(dataType: unknown, value: unknown): string {
+  if (value == null) return '—'
+  if (isReferenceValue(value)) return value.display
+
+  const kind = dataTypeKind(dataType)
+
+  if (kind === 'Boolean') return value ? 'Yes' : 'No'
+
+  if (kind === 'Int32') {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed.toLocaleString(undefined, { maximumFractionDigits: 0 })
+  }
+
+  if (kind === 'Decimal' || kind === 'Money') {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) {
+      return parsed.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+    }
+  }
+
+  if (kind === 'Date') {
+    const raw = typeof value === 'string' ? value : String(value)
+    const dateOnly = tryFormatDateOnly(raw)
+    if (dateOnly) return dateOnly
+
+    const date = new Date(value as string | number | Date)
+    if (!Number.isNaN(date.getTime())) return date.toLocaleDateString()
+  }
+
+  if (kind === 'DateTime') {
+    const date = new Date(value as string | number | Date)
+    if (!Number.isNaN(date.getTime())) return date.toLocaleString()
+  }
+
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+export function buildMetadataRegisterColumns(args: BuildColumnsArgs): RegisterColumn[] {
+  return args.columns.map((column) => ({
+    key: column.key,
+    title: prettifyRegisterTitle(column.label, column.key),
+    width: column.widthPx ?? undefined,
+    align: alignFromDto(column.align),
+    sortable: column.isSortable,
+    format: (value: unknown) => {
+      const override = args.formatOverride?.(column, value)
+      if (override != null) return override
+
+      const normalizedValue = String(value ?? '').trim()
+      const optionLabel = args.optionLabelsByColumnKey?.[column.key]?.get(normalizedValue)
+        ?? column.options?.find((entry) => String(entry.value ?? '').trim() === normalizedValue)?.label
+      if (optionLabel) return optionLabel
+
+      return formatRegisterValue(column.dataType, value)
+    },
+  }))
+}
+
+export function buildMetadataRegisterRows<TItem extends RegisterRecordItem>(args: BuildRowsArgs<TItem>): RegisterRow[] {
+  return args.items.map((item) => {
+    const fields = (item.payload?.fields ?? {}) as RecordFields
+    const row: RegisterRow = {
+      key: item.id,
+      isDeleted: item.isDeleted,
+      isMarkedForDeletion: item.isMarkedForDeletion,
+      status: item.status,
+    }
+
+    for (const column of args.columns) {
+      const rawValue = fields[column.key]
+      row[column.key] = args.mapFieldValue?.(column, rawValue, item) ?? rawValue
+    }
+
+    args.extendRow?.(row, item)
+    return row
+  })
+}

package/src/ngb/metadata/routePages.ts

@@ -0,0 +1,86 @@
+import type { Component } from 'vue'
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router'
+
+import type { EntityEditorFlags, EntityHeaderIconAction } from '../editor/types'
+import type { QueryTrashMode } from '../router/queryParams'
+import type { Awaitable, LookupHint, LookupSource } from './types'
+import type { MetadataRegisterPageMetadata, MetadataRegisterPageResponse } from './useMetadataRegisterPageData'
+
+export type MetadataCatalogListPageLoadArgs = {
+  catalogType: string
+  offset: number
+  limit: number
+  search?: string
+  trashMode: QueryTrashMode
+}
+
+export type MetadataCatalogDrawerActionArgs = {
+  action: string
+  editor: unknown | null
+}
+
+export interface MetadataCatalogListPageProps {
+  editorComponent: Component
+  loadPage: (args: MetadataCatalogListPageLoadArgs) => Promise<MetadataRegisterPageResponse>
+  resolveTitle?: ((catalogType: string, displayName: string) => string) | null
+  resolveStorageKey?: ((catalogType: string) => string | null | undefined) | null
+  resolveDrawerExtraActions?: ((args: { editorFlags: EntityEditorFlags }) => EntityHeaderIconAction[]) | null
+  handleDrawerExtraAction?: ((args: MetadataCatalogDrawerActionArgs) => Awaitable<boolean | void>) | null
+  backTarget?: string | null
+}
+
+export interface MetadataCatalogEditPageProps {
+  editorComponent: Component
+  canBack?: boolean
+  resolveCompactTo?: ((catalogType: string, id?: string | null) => string | null | undefined) | null
+  resolveCloseTo?: ((catalogType: string) => string | null | undefined) | null
+}
+
+export type MetadataDocumentListPageLoadArgs<TMeta extends MetadataRegisterPageMetadata = MetadataRegisterPageMetadata> = {
+  documentType: string
+  metadata: TMeta
+  offset: number
+  limit: number
+  search?: string
+  trashMode: QueryTrashMode
+  periodFrom?: string | null
+  periodTo?: string | null
+  listFilters: Record<string, string>
+}
+
+export type MetadataRouteLocationLike = Pick<RouteLocationNormalizedLoaded, 'fullPath' | 'params' | 'query'>
+
+export type MetadataRouterLike = Pick<Router, 'push'>
+
+export type MetadataDocumentCreateOverrideArgs<TMeta extends MetadataRegisterPageMetadata = MetadataRegisterPageMetadata> = {
+  documentType: string
+  metadata: TMeta | null
+  preferFullPage: boolean
+  route: MetadataRouteLocationLike
+  router: MetadataRouterLike
+  openCreateDrawer: (copyDraftToken?: string | null) => void
+  openFullPage: () => Promise<void>
+}
+
+export interface MetadataDocumentListPageProps<TMeta extends MetadataRegisterPageMetadata = MetadataRegisterPageMetadata> {
+  editorComponent: Component
+  loadPage: (args: MetadataDocumentListPageLoadArgs<TMeta>) => Promise<MetadataRegisterPageResponse>
+  resolveLookupHint?: ((args: {
+    entityTypeCode: string
+    fieldKey: string
+    lookup?: LookupSource | null
+  }) => LookupHint | null) | null
+  resolveTitle?: ((documentType: string, displayName: string) => string) | null
+  resolveStorageKey?: ((documentType: string) => string | null | undefined) | null
+  resolveWarning?: ((documentType: string, metadata: TMeta | null) => string | null | undefined) | null
+  isCreateDisabled?: ((documentType: string, metadata: TMeta | null) => boolean) | null
+  handleCreateOverride?: ((args: MetadataDocumentCreateOverrideArgs<TMeta>) => Awaitable<boolean | void>) | null
+  backTarget?: string | null
+}
+
+export interface MetadataDocumentEditPageProps {
+  editorComponent: Component
+  canBack?: boolean
+  resolveCompactTo?: ((documentType: string, id?: string | null) => string | null | undefined) | null
+  resolveCloseTo?: ((documentType: string) => string | null | undefined) | null
+}

package/src/ngb/metadata/store.ts

@@ -0,0 +1,35 @@
+import { defineStore } from 'pinia'
+import { getConfiguredNgbMetadata } from './config'
+import { normalizeCatalogTypeMetadata, normalizeDocumentTypeMetadata } from './normalization'
+import type { CatalogTypeMetadata, DocumentTypeMetadata } from './types'
+
+export const useMetadataStore = defineStore('metadata', {
+  state: () => ({
+    catalogs: {} as Record<string, CatalogTypeMetadata>,
+    documents: {} as Record<string, DocumentTypeMetadata>,
+  }),
+  actions: {
+    async ensureCatalogType(catalogType: string): Promise<CatalogTypeMetadata> {
+      if (!this.catalogs[catalogType]) {
+        const config = getConfiguredNgbMetadata()
+        this.catalogs[catalogType] = normalizeCatalogTypeMetadata(await config.loadCatalogTypeMetadata(catalogType))
+      }
+
+      return this.catalogs[catalogType]
+    },
+
+    async ensureDocumentType(documentType: string): Promise<DocumentTypeMetadata> {
+      if (!this.documents[documentType]) {
+        const config = getConfiguredNgbMetadata()
+        this.documents[documentType] = normalizeDocumentTypeMetadata(await config.loadDocumentTypeMetadata(documentType))
+      }
+
+      return this.documents[documentType]
+    },
+
+    clear() {
+      this.catalogs = {}
+      this.documents = {}
+    },
+  },
+})