@ngbplatform/ui 1.3.0

package/src/ngb/reporting/config.ts

@@ -0,0 +1,120 @@
+import { buildChartOfAccountsPath } from '../accounting/navigation'
+import { buildCatalogFullPageUrl } from '../editor/catalogNavigation'
+import { buildDocumentFullPageUrl } from '../editor/documentNavigation'
+import type { Awaitable, LookupSource } from '../metadata/types'
+import { withBackTarget } from '../router/backNavigation'
+import { isGuidString } from '../utils/guid'
+import type { ReportLookupStoreApi } from './lookupFilters'
+import { appendSourceTrail, buildReportPageUrl, type ReportRouteContext, type ReportSourceTrail } from './navigation'
+import type { ReportCellActionDto } from './types'
+
+export type ReportLookupTargetArgs = {
+  hint: LookupSource | null
+  value: unknown
+  routeFullPath: string
+}
+
+export type ReportCellActionNavigationOptions = {
+  currentReportContext?: ReportRouteContext | null
+  sourceTrail?: ReportSourceTrail | null
+  backTarget?: string | null
+}
+
+export type ReportingFrameworkConfig = {
+  useLookupStore: () => ReportLookupStoreApi
+  resolveLookupTarget?: (args: ReportLookupTargetArgs) => Awaitable<string | null>
+  resolveCellActionUrl?: (
+    action: ReportCellActionDto | null | undefined,
+    options?: ReportCellActionNavigationOptions,
+  ) => string | null
+}
+
+let configuredReporting: ReportingFrameworkConfig | null = null
+
+function buildOpenReportActionUrl(
+  action: ReportCellActionDto,
+  options?: ReportCellActionNavigationOptions,
+): string | null {
+  const reportCode = String(action.report?.reportCode ?? '').trim()
+  if (!reportCode) return null
+
+  return buildReportPageUrl(reportCode, {
+    context: {
+      reportCode,
+      request: {
+        parameters: action.report?.parameters ?? null,
+        filters: action.report?.filters ?? null,
+        layout: null,
+        offset: 0,
+        limit: 500,
+        cursor: null,
+      },
+    },
+    sourceTrail: appendSourceTrail(options?.sourceTrail ?? null, options?.currentReportContext ?? null),
+    backTarget: options?.backTarget ?? null,
+  })
+}
+
+function withOptionalBackTarget(url: string, backTarget?: string | null): string {
+  return withBackTarget(url, backTarget ?? null)
+}
+
+export function configureNgbReporting(config: ReportingFrameworkConfig) {
+  configuredReporting = config
+}
+
+export function getConfiguredNgbReporting(): ReportingFrameworkConfig {
+  if (!configuredReporting) {
+    throw new Error('NGB reporting framework is not configured. Call configureNgbReporting(...) during app bootstrap.')
+  }
+
+  return configuredReporting
+}
+
+export function maybeGetConfiguredNgbReporting(): ReportingFrameworkConfig | null {
+  return configuredReporting
+}
+
+export async function resolveReportLookupTarget(args: ReportLookupTargetArgs): Promise<string | null> {
+  const resolver = getConfiguredNgbReporting().resolveLookupTarget
+  if (!resolver) return null
+  return await resolver(args)
+}
+
+export function resolveReportCellActionUrl(
+  action: ReportCellActionDto | null | undefined,
+  options?: ReportCellActionNavigationOptions,
+): string | null {
+  const configured = maybeGetConfiguredNgbReporting()
+  const configuredTarget = configured?.resolveCellActionUrl?.(action, options)
+  if (configuredTarget) return configuredTarget
+  if (!action || !action.kind) return null
+
+  try {
+    if (action.kind === 'open_document') {
+      const documentType = String(action.documentType ?? '').trim()
+      const id = String(action.documentId ?? '').trim()
+      if (!documentType || !id || !isGuidString(id)) return null
+      return withOptionalBackTarget(buildDocumentFullPageUrl(documentType, id), options?.backTarget)
+    }
+
+    if (action.kind === 'open_account') {
+      const accountId = String(action.accountId ?? '').trim()
+      if (!accountId || !isGuidString(accountId)) return null
+      return withOptionalBackTarget(buildChartOfAccountsPath({ panel: 'edit', id: accountId }), options?.backTarget)
+    }
+
+    if (action.kind === 'open_catalog') {
+      const catalogType = String(action.catalogType ?? '').trim()
+      const id = String(action.catalogId ?? '').trim()
+      if (!catalogType || !id || !isGuidString(id)) return null
+      return withOptionalBackTarget(buildCatalogFullPageUrl(catalogType, id), options?.backTarget)
+    }
+
+    if (action.kind === 'open_report') return buildOpenReportActionUrl(action, options)
+  } catch {
+    return null
+  }
+
+  return null
+}

package/src/ngb/reporting/defaultConfig.ts

@@ -0,0 +1,15 @@
+import { buildLookupFieldTargetUrl } from '../lookup/navigation'
+import { useLookupStore } from '../lookup/store'
+import type { ReportingFrameworkConfig } from './config'
+
+export function createDefaultNgbReportingConfig(): ReportingFrameworkConfig {
+  return {
+    useLookupStore: () => useLookupStore(),
+    resolveLookupTarget: async ({ hint, value, routeFullPath }) =>
+      await buildLookupFieldTargetUrl({
+        hint,
+        value,
+        route: { fullPath: routeFullPath },
+      }),
+  }
+}

package/src/ngb/reporting/lookupFilters.ts

@@ -0,0 +1,43 @@
+import {
+  extractLookupIds,
+  hydrateResolvedLookupItems,
+  searchResolvedLookupItems,
+} from '../metadata/filtering'
+import type { LookupStoreApi } from '../metadata/types'
+import type {
+  ReportComposerDraft,
+  ReportComposerLookupItem,
+  ReportDefinitionDto,
+  ReportFilterValueDto,
+} from './types'
+
+export type ReportLookupStoreApi = LookupStoreApi<ReportComposerLookupItem>
+
+export async function searchReportLookupItems(
+  lookupStore: ReportLookupStoreApi,
+  lookup: NonNullable<NonNullable<ReportDefinitionDto['filters']>[number]['lookup']>,
+  query: string,
+): Promise<ReportComposerLookupItem[]> {
+  return await searchResolvedLookupItems(lookupStore, lookup, query)
+}
+
+export async function hydrateReportLookupItemsFromFilters(
+  lookupStore: ReportLookupStoreApi,
+  definition: Pick<ReportDefinitionDto, 'filters'>,
+  draft: ReportComposerDraft,
+  filters: Record<string, ReportFilterValueDto> | null | undefined,
+): Promise<void> {
+  if (!filters) return
+
+  for (const field of definition.filters ?? []) {
+    const state = draft.filters[field.fieldCode]
+    const filterValue = filters[field.fieldCode]
+    if (!state || !field.lookup || !filterValue) continue
+
+    const ids = extractLookupIds(filterValue.value)
+    if (ids.length === 0) continue
+
+    state.items = await hydrateResolvedLookupItems(lookupStore, field.lookup, ids)
+    if (state.items.length > 0) state.raw = ''
+  }
+}

package/src/ngb/reporting/navigation.ts

@@ -0,0 +1,181 @@
+import { withBackTarget } from '../router/backNavigation'
+import { buildExecutionRequest } from './composer'
+import type { ReportComposerDraft, ReportDefinitionDto, ReportExecutionRequestDto, ReportFilterValueDto } from './types'
+
+export type ReportRouteContext = {
+  reportCode: string
+  reportName?: string | null
+  request: ReportExecutionRequestDto
+}
+
+export type ReportSourceTrail = {
+  items: ReportRouteContext[]
+}
+
+type ReportTokenPayload = {
+  reportCode: string
+  parameters?: Record<string, string> | null
+  filters?: Record<string, ReportFilterValueDto> | null
+}
+
+function normalizeQueryValue(value: unknown): string | null {
+  if (Array.isArray(value)) return normalizeQueryValue(value[0] ?? null)
+  const raw = String(value ?? '').trim()
+  return raw.length > 0 ? raw : null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function encodeBase64UrlJson(value: unknown): string {
+  const bytes = new TextEncoder().encode(JSON.stringify(value))
+  let binary = ''
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte)
+  })
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+function decodeBase64UrlJson<T>(value: unknown): T | null {
+  const raw = normalizeQueryValue(value)
+  if (!raw) return null
+
+  try {
+    const padded = raw.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((raw.length + 3) % 4)
+    const binary = atob(padded)
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0))
+    return JSON.parse(new TextDecoder().decode(bytes)) as T
+  } catch {
+    return null
+  }
+}
+
+function normalizeFilterValue(value: unknown): ReportFilterValueDto | null {
+  if (!isPlainObject(value) || !('value' in value)) return null
+  return {
+    value: value.value,
+    includeDescendants: !!value.includeDescendants,
+  }
+}
+
+function normalizeExecutionRequest(value: unknown): ReportExecutionRequestDto | null {
+  if (!isPlainObject(value)) return null
+
+  const parameters = isPlainObject(value.parameters)
+    ? Object.fromEntries(Object.entries(value.parameters).map(([key, entry]) => [key, String(entry ?? '').trim()]).filter(([, entry]) => entry.length > 0))
+    : null
+
+  const filters = isPlainObject(value.filters)
+    ? Object.fromEntries(Object.entries(value.filters).map(([key, entry]) => [key, normalizeFilterValue(entry)]).filter((entry): entry is [string, ReportFilterValueDto] => !!entry[1]))
+    : null
+
+  const layout = isPlainObject(value.layout) ? (value.layout as ReportExecutionRequestDto['layout']) : null
+  const variantCode = typeof value.variantCode === 'string' && value.variantCode.trim().length > 0 ? value.variantCode.trim() : null
+  const offset = typeof value.offset === 'number' && Number.isFinite(value.offset) ? value.offset : 0
+  const limit = typeof value.limit === 'number' && Number.isFinite(value.limit) ? value.limit : 500
+  const cursor = typeof value.cursor === 'string' && value.cursor.trim().length > 0 ? value.cursor.trim() : null
+
+  return {
+    layout,
+    parameters: parameters && Object.keys(parameters).length > 0 ? parameters : null,
+    filters: filters && Object.keys(filters).length > 0 ? filters : null,
+    variantCode,
+    offset,
+    limit,
+    cursor,
+  }
+}
+
+function normalizeRouteContext(value: unknown): ReportRouteContext | null {
+  if (!isPlainObject(value)) return null
+  const reportCode = String(value.reportCode ?? '').trim()
+  if (!reportCode) return null
+  const request = normalizeExecutionRequest(value.request)
+  if (!request) return null
+  const reportName = typeof value.reportName === 'string' && value.reportName.trim().length > 0 ? value.reportName.trim() : null
+  return { reportCode, reportName, request }
+}
+
+export function encodeReportRouteContextParam(value: ReportRouteContext | null | undefined): string | null {
+  return value ? encodeBase64UrlJson(value) : null
+}
+
+export function encodeReportSourceTrailParam(value: ReportSourceTrail | null | undefined): string | null {
+  return value && value.items.length > 0 ? encodeBase64UrlJson(value) : null
+}
+
+export function buildCurrentReportContext(definition: ReportDefinitionDto, draft: ReportComposerDraft): ReportRouteContext {
+  return {
+    reportCode: definition.reportCode,
+    reportName: definition.name,
+    request: buildExecutionRequest(definition, draft),
+  }
+}
+
+export function buildReportPageUrl(
+  reportCode: string,
+  options?: {
+    context?: ReportRouteContext | null
+    sourceTrail?: ReportSourceTrail | null
+    backTarget?: string | null
+  },
+): string {
+  const path = `/reports/${encodeURIComponent(reportCode)}`
+  const query = new URLSearchParams()
+  const contextParam = encodeReportRouteContextParam(options?.context)
+  const sourceTrailParam = encodeReportSourceTrailParam(options?.sourceTrail)
+  if (contextParam) query.set('ctx', contextParam)
+  if (sourceTrailParam) query.set('src', sourceTrailParam)
+  const suffix = query.toString()
+  const url = suffix ? `${path}?${suffix}` : path
+  return withBackTarget(url, options?.backTarget ?? null)
+}
+
+export function decodeReportRouteContextParam(value: unknown): ReportRouteContext | null {
+  return normalizeRouteContext(decodeBase64UrlJson(value))
+}
+
+export function decodeReportSourceTrailParam(value: unknown): ReportSourceTrail | null {
+  const decoded = decodeBase64UrlJson<{ items?: unknown }>(value)
+  if (!decoded || !Array.isArray(decoded.items)) return null
+  const items = decoded.items.map(normalizeRouteContext).filter((entry): entry is ReportRouteContext => !!entry)
+  return items.length > 0 ? { items } : null
+}
+
+export function decodeReportDrilldownTarget(token: string | null | undefined): ReportRouteContext | null {
+  const raw = String(token ?? '').trim()
+  if (!raw.startsWith('report:')) return null
+  const payload = decodeBase64UrlJson<ReportTokenPayload>(raw.slice('report:'.length))
+  if (!payload || typeof payload.reportCode !== 'string' || payload.reportCode.trim().length === 0) return null
+
+  return {
+    reportCode: payload.reportCode.trim(),
+    request: {
+      parameters: payload.parameters && Object.keys(payload.parameters).length > 0 ? payload.parameters : null,
+      filters: payload.filters && Object.keys(payload.filters).length > 0 ? payload.filters : null,
+      layout: null,
+      offset: 0,
+      limit: 500,
+      cursor: null,
+    },
+  }
+}
+
+export function appendSourceTrail(sourceTrail: ReportSourceTrail | null | undefined, currentContext: ReportRouteContext | null | undefined): ReportSourceTrail | null {
+  const items = [...(sourceTrail?.items ?? [])]
+  if (currentContext) items.push(currentContext)
+  return items.length > 0 ? { items } : null
+}
+
+export function buildBackToSourceUrl(sourceTrail: ReportSourceTrail | null | undefined, backTarget?: string | null): string | null {
+  const items = sourceTrail?.items ?? []
+  if (items.length === 0) return null
+  const target = items[items.length - 1]!
+  const priorItems = items.slice(0, -1)
+  return buildReportPageUrl(target.reportCode, {
+    context: target,
+    sourceTrail: priorItems.length > 0 ? { items: priorItems } : null,
+    backTarget: backTarget ?? null,
+  })
+}

package/src/ngb/reporting/pageHelpers.ts

@@ -0,0 +1,73 @@
+import { optionLabelForFilter } from '../metadata/filtering'
+import { normalizeDateOnlyValue } from '../utils/dateValues'
+import { slugifyVariantCode } from './composer'
+import type {
+  ReportComposerDraft,
+  ReportDefinitionDto,
+  ReportFilterFieldDto,
+  ReportVariantDto,
+} from './types'
+
+export type ReportPageBadge = {
+  key: string
+  text: string
+}
+
+export function hasFilterStateValue(field: ReportFilterFieldDto, composer: ReportComposerDraft): boolean {
+  const state = composer.filters[field.fieldCode]
+  if (!state) return false
+  if (state.items.length > 0) return true
+  return state.raw.trim().length > 0
+}
+
+export function canAutoRunReport(definition: ReportDefinitionDto, composer: ReportComposerDraft): boolean {
+  const missingParameter = (definition.parameters ?? []).some((parameter) => parameter.isRequired && String(composer.parameters[parameter.code] ?? '').trim().length === 0)
+  if (missingParameter) return false
+  return !(definition.filters ?? []).some((field) => field.isRequired && !hasFilterStateValue(field, composer))
+}
+
+export function normalizeParameterDataType(dataType: string): string {
+  return dataType.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_')
+}
+
+export function isInlineDateParameterDataType(dataType: string): boolean {
+  const normalized = normalizeParameterDataType(dataType)
+  return normalized === 'date' || normalized === 'date_only' || normalized === 'date_time_utc'
+}
+
+export function parameterLabel(parameter: { code: string; label?: string | null }): string {
+  return String(parameter.label ?? parameter.code).trim() || String(parameter.code ?? '').trim()
+}
+
+export function normalizeReportDateValue(value: unknown): string | null {
+  return normalizeDateOnlyValue(String(value ?? '').trim())
+}
+
+export function normalizeCode(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_')
+}
+
+export function tryResolveOptionLabel(field: ReportFilterFieldDto, rawValue: string): string {
+  const normalized = rawValue.trim()
+  if (normalized.length === 0) return normalized
+  return optionLabelForFilter(field, normalized) || normalized
+}
+
+export function chooseAvailableVariantCode(
+  name: string,
+  variants: readonly ReportVariantDto[],
+  exceptVariantCode?: string | null,
+): string {
+  const base = slugifyVariantCode(name)
+
+  let candidate = base
+  let suffix = 2
+  const except = String(exceptVariantCode ?? '').trim()
+
+  while (variants.some((variant) => variant.variantCode === candidate && variant.variantCode !== except)) {
+    candidate = `${base}-${suffix}`
+    suffix += 1
+  }
+
+  return candidate
+}

package/src/ngb/reporting/pageSession.ts

@@ -0,0 +1,92 @@
+import {
+  readStorageJsonOrNull,
+  readStorageString,
+  removeStorageItem,
+  writeStorageJson,
+  writeStorageString,
+} from '../utils/storage'
+
+import type { ReportExecutionResponseDto } from './types'
+
+const EXECUTION_PREFIX = 'ngb.report.page.execution:'
+const SCROLL_PREFIX = 'ngb.report.page.scroll:'
+
+export type ReportPageExecutionSnapshot = {
+  response: ReportExecutionResponseDto
+  consumedCursors: string[]
+}
+
+function normalizeKey(key: string | null | undefined): string | null {
+  const normalized = String(key ?? '').trim()
+  return normalized.length > 0 ? normalized : null
+}
+
+function executionStorageKey(routeStateKey: string | null | undefined): string | null {
+  const normalized = normalizeKey(routeStateKey)
+  return normalized ? `${EXECUTION_PREFIX}${normalized}` : null
+}
+
+function scrollStorageKey(routeStateKey: string | null | undefined): string | null {
+  const normalized = normalizeKey(routeStateKey)
+  return normalized ? `${SCROLL_PREFIX}${normalized}` : null
+}
+
+export function saveReportPageExecutionSnapshot(
+  routeStateKey: string | null | undefined,
+  response: ReportExecutionResponseDto,
+  consumedCursors: string[],
+) {
+  const storageKey = executionStorageKey(routeStateKey ?? null)
+  if (!storageKey) return
+
+  void writeStorageJson('session', storageKey, {
+    response,
+    consumedCursors: Array.from(new Set((consumedCursors ?? []).map((entry) => String(entry ?? '').trim()).filter((entry) => entry.length > 0))),
+  } satisfies ReportPageExecutionSnapshot)
+}
+
+export function loadReportPageExecutionSnapshot(routeStateKey: string | null | undefined): ReportPageExecutionSnapshot | null {
+  const storageKey = executionStorageKey(routeStateKey ?? null)
+  if (!storageKey) return null
+
+  const snapshot = readStorageJsonOrNull<ReportPageExecutionSnapshot>('session', storageKey)
+  if (!snapshot?.response?.sheet) return null
+
+  return {
+    response: snapshot.response,
+    consumedCursors: Array.from(new Set((snapshot.consumedCursors ?? []).map((entry) => String(entry ?? '').trim()).filter((entry) => entry.length > 0))),
+  }
+}
+
+export function clearReportPageExecutionSnapshot(routeStateKey: string | null | undefined) {
+  const storageKey = executionStorageKey(routeStateKey ?? null)
+  if (!storageKey) return
+  removeStorageItem('session', storageKey)
+}
+
+export function saveReportPageScrollTop(routeStateKey: string | null | undefined, scrollTop: number) {
+  const storageKey = scrollStorageKey(routeStateKey ?? null)
+  if (!storageKey) return
+
+  const normalized = Number.isFinite(scrollTop) && scrollTop > 0 ? Math.floor(scrollTop) : 0
+  if (normalized <= 0) {
+    removeStorageItem('session', storageKey)
+    return
+  }
+
+  void writeStorageString('session', storageKey, String(normalized))
+}
+
+export function loadReportPageScrollTop(routeStateKey: string | null | undefined): number {
+  const storageKey = scrollStorageKey(routeStateKey ?? null)
+  if (!storageKey) return 0
+
+  const parsed = Number(readStorageString('session', storageKey) ?? '')
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0
+}
+
+export function clearReportPageScrollTop(routeStateKey: string | null | undefined) {
+  const storageKey = scrollStorageKey(routeStateKey ?? null)
+  if (!storageKey) return
+  removeStorageItem('session', storageKey)
+}

package/src/ngb/reporting/paging.ts

@@ -0,0 +1,66 @@
+import { ReportRowKind, type ReportExecutionRequestDto, type ReportExecutionResponseDto, type ReportSheetDto, type ReportSheetRowDto } from './types'
+import { stableEquals } from '../utils/stableValue'
+
+function normalizeCursor(value: string | null | undefined): string | null {
+  const normalized = String(value ?? '').trim()
+  return normalized.length > 0 ? normalized : null
+}
+
+function isGrandTotalRow(row: ReportSheetRowDto | null | undefined): boolean {
+  if (!row) return false
+  if (row.rowKind === ReportRowKind.Total) return true
+  return String(row.semanticRole ?? '').trim().toLowerCase() === 'grand_total'
+}
+
+export function countLoadedReportRows(sheet: ReportSheetDto | null | undefined): number {
+  const rows = sheet?.rows ?? []
+  return rows.reduce((count, row) => count + (isGrandTotalRow(row) ? 0 : 1), 0)
+}
+
+function cloneSheetWithRows(sheet: ReportSheetDto, rows: ReportSheetDto['rows']): ReportSheetDto {
+  return {
+    columns: [...(sheet.columns ?? [])],
+    rows,
+    meta: sheet.meta ?? null,
+    headerRows: sheet.headerRows ? [...sheet.headerRows] : null,
+  }
+}
+
+function areSheetsAppendCompatible(left: ReportSheetDto, right: ReportSheetDto): boolean {
+  return stableEquals(left.columns ?? [], right.columns ?? [])
+    && stableEquals(left.headerRows ?? [], right.headerRows ?? [])
+}
+
+export function canAppendReportResponse(response: ReportExecutionResponseDto | null | undefined): boolean {
+  return !!response?.hasMore && !!normalizeCursor(response.nextCursor)
+}
+
+export function buildAppendRequest(baseRequest: ReportExecutionRequestDto, nextCursor: string): ReportExecutionRequestDto {
+  return {
+    ...baseRequest,
+    offset: 0,
+    limit: Math.max(1, baseRequest.limit ?? 500),
+    cursor: normalizeCursor(nextCursor),
+  }
+}
+
+export function mergePagedReportResponses(
+  current: ReportExecutionResponseDto,
+  next: ReportExecutionResponseDto,
+): ReportExecutionResponseDto {
+  if (!areSheetsAppendCompatible(current.sheet, next.sheet)) {
+    throw new Error('Paged report append returned an incompatible sheet shape.')
+  }
+
+  const mergedRows = [...(current.sheet.rows ?? []), ...(next.sheet.rows ?? [])]
+
+  return {
+    sheet: cloneSheetWithRows(current.sheet, mergedRows),
+    offset: current.offset,
+    limit: current.limit,
+    total: next.total ?? current.total ?? mergedRows.length,
+    hasMore: next.hasMore,
+    nextCursor: normalizeCursor(next.nextCursor),
+    diagnostics: next.diagnostics ?? current.diagnostics,
+  }
+}