@ngbplatform/ui 1.3.0

package/src/ngb/reporting/types.ts

@@ -0,0 +1,333 @@
+import type { LookupItem, LookupSource } from '../metadata/types'
+
+export enum ReportAggregationKind {
+  Sum = 1,
+  Min = 2,
+  Max = 3,
+  Average = 4,
+  Count = 5,
+  CountDistinct = 6,
+  First = 7,
+  Last = 8,
+}
+
+export enum ReportExecutionMode {
+  Canonical = 1,
+  Composable = 2,
+}
+
+export enum ReportFieldKind {
+  Attribute = 1,
+  Dimension = 2,
+  Time = 3,
+  Detail = 4,
+  System = 5,
+}
+
+export enum ReportTimeGrain {
+  Day = 1,
+  Week = 2,
+  Month = 3,
+  Quarter = 4,
+  Year = 5,
+}
+
+export enum ReportSortDirection {
+  Asc = 1,
+  Desc = 2,
+}
+
+export enum ReportRowKind {
+  Header = 1,
+  Group = 2,
+  Detail = 3,
+  Subtotal = 4,
+  Total = 5,
+}
+
+export type ReportCapabilitiesDto = {
+  allowsFilters?: boolean
+  allowsRowGroups?: boolean
+  allowsColumnGroups?: boolean
+  allowsMeasures?: boolean
+  allowsDetailFields?: boolean
+  allowsSorting?: boolean
+  allowsShowDetails?: boolean
+  allowsSubtotals?: boolean
+  allowsSeparateRowSubtotals?: boolean
+  allowsGrandTotals?: boolean
+  allowsVariants?: boolean
+  allowsXlsxExport?: boolean
+  maxRowGroupDepth?: number | null
+  maxColumnGroupDepth?: number | null
+  maxVisibleColumns?: number | null
+  maxVisibleRows?: number | null
+  maxRenderedCells?: number | null
+}
+
+export type ReportPresentationDto = {
+  initialPageSize?: number | null
+  rowNoun?: string | null
+  emptyStateMessage?: string | null
+}
+
+export type ReportFieldDto = {
+  code: string
+  label: string
+  dataType: string
+  kind: ReportFieldKind
+  isFilterable?: boolean
+  isGroupable?: boolean
+  isSortable?: boolean
+  isSelectable?: boolean
+  supportsIncludeDescendants?: boolean
+  defaultIncludeDescendants?: boolean
+  supportedTimeGrains?: ReportTimeGrain[] | null
+  lookup?: LookupSource | null
+  description?: string | null
+  format?: string | null
+}
+
+export type ReportMeasureDto = {
+  code: string
+  label: string
+  dataType: string
+  supportedAggregations?: ReportAggregationKind[] | null
+  format?: string | null
+  description?: string | null
+}
+
+export type ReportDatasetDto = {
+  datasetCode: string
+  fields?: ReportFieldDto[] | null
+  measures?: ReportMeasureDto[] | null
+}
+
+export type ReportParameterMetadataDto = {
+  code: string
+  dataType: string
+  isRequired: boolean
+  description?: string | null
+  defaultValue?: string | null
+  label?: string | null
+}
+
+export type ReportFilterOptionDto = {
+  value: string
+  label: string
+}
+
+export type ReportFilterFieldDto = {
+  fieldCode: string
+  label: string
+  dataType: string
+  isRequired?: boolean
+  isMulti?: boolean
+  supportsIncludeDescendants?: boolean
+  defaultIncludeDescendants?: boolean
+  lookup?: LookupSource | null
+  options?: ReportFilterOptionDto[] | null
+  description?: string | null
+}
+
+export type ReportGroupingDto = {
+  fieldCode: string
+  timeGrain?: ReportTimeGrain | null
+  includeDetails?: boolean
+  includeEmpty?: boolean
+  includeDescendants?: boolean
+  labelOverride?: string | null
+  groupKey?: string | null
+}
+
+export type ReportMeasureSelectionDto = {
+  measureCode: string
+  aggregation?: ReportAggregationKind
+  labelOverride?: string | null
+  formatOverride?: string | null
+}
+
+export type ReportSortDto = {
+  fieldCode: string
+  direction?: ReportSortDirection
+  timeGrain?: ReportTimeGrain | null
+  appliesToColumnAxis?: boolean
+  groupKey?: string | null
+}
+
+export type ReportLayoutDto = {
+  rowGroups?: ReportGroupingDto[] | null
+  columnGroups?: ReportGroupingDto[] | null
+  measures?: ReportMeasureSelectionDto[] | null
+  detailFields?: string[] | null
+  sorts?: ReportSortDto[] | null
+  showDetails?: boolean
+  showSubtotals?: boolean
+  showSubtotalsOnSeparateRows?: boolean
+  showGrandTotals?: boolean
+}
+
+export type ReportDefinitionDto = {
+  reportCode: string
+  name: string
+  group?: string | null
+  description?: string | null
+  mode?: ReportExecutionMode
+  dataset?: ReportDatasetDto | null
+  capabilities?: ReportCapabilitiesDto | null
+  defaultLayout?: ReportLayoutDto | null
+  parameters?: ReportParameterMetadataDto[] | null
+  filters?: ReportFilterFieldDto[] | null
+  presentation?: ReportPresentationDto | null
+}
+
+export type ReportFilterValueDto = {
+  value: unknown
+  includeDescendants?: boolean
+}
+
+export type ReportExportRequestDto = {
+  layout?: ReportLayoutDto | null
+  filters?: Record<string, ReportFilterValueDto> | null
+  parameters?: Record<string, string> | null
+  variantCode?: string | null
+}
+
+export type ReportExecutionRequestDto = {
+  layout?: ReportLayoutDto | null
+  filters?: Record<string, ReportFilterValueDto> | null
+  parameters?: Record<string, string> | null
+  variantCode?: string | null
+  offset?: number
+  limit?: number
+  cursor?: string | null
+}
+
+export type ReportCellReportTargetDto = {
+  reportCode: string
+  parameters?: Record<string, string> | null
+  filters?: Record<string, ReportFilterValueDto> | null
+}
+
+export type ReportCellActionDto = {
+  kind: string
+  documentType?: string | null
+  documentId?: string | null
+  accountId?: string | null
+  catalogType?: string | null
+  catalogId?: string | null
+  report?: ReportCellReportTargetDto | null
+}
+
+export type ReportCellDto = {
+  value?: unknown
+  display?: string | null
+  valueType?: string | null
+  colSpan?: number
+  rowSpan?: number
+  styleKey?: string | null
+  semanticRole?: string | null
+  action?: ReportCellActionDto | null
+}
+
+export type ReportSheetColumnDto = {
+  code: string
+  title: string
+  dataType: string
+  width?: number
+  isFrozen?: boolean
+  semanticRole?: string | null
+}
+
+export type ReportSheetRowDto = {
+  rowKind: ReportRowKind
+  cells: ReportCellDto[]
+  outlineLevel?: number
+  isExpanded?: boolean
+  groupKey?: string | null
+  semanticRole?: string | null
+}
+
+export type ReportSheetMetaDto = {
+  title?: string | null
+  subtitle?: string | null
+  isPivot?: boolean
+  hasRowOutline?: boolean
+  hasColumnGroups?: boolean
+  diagnostics?: Record<string, string> | null
+}
+
+export type ReportSheetDto = {
+  columns: ReportSheetColumnDto[]
+  rows: ReportSheetRowDto[]
+  meta?: ReportSheetMetaDto | null
+  headerRows?: ReportSheetRowDto[] | null
+}
+
+export type ReportExecutionResponseDto = {
+  sheet: ReportSheetDto
+  offset: number
+  limit: number
+  total?: number | null
+  hasMore: boolean
+  nextCursor?: string | null
+  diagnostics?: Record<string, string> | null
+}
+
+export type ReportVariantDto = {
+  variantCode: string
+  reportCode: string
+  name: string
+  layout?: ReportLayoutDto | null
+  filters?: Record<string, ReportFilterValueDto> | null
+  parameters?: Record<string, string> | null
+  isDefault?: boolean
+  isShared?: boolean
+}
+
+export type ReportComposerLookupItem = LookupItem
+
+export type ReportComposerFilterState = {
+  raw: string
+  items: ReportComposerLookupItem[]
+  includeDescendants: boolean
+}
+
+export type ReportComposerGroupingState = {
+  groupKey?: string | null
+  fieldCode: string
+  timeGrain: ReportTimeGrain | null
+}
+
+export type ReportComposerMeasureState = {
+  measureCode: string
+  aggregation: ReportAggregationKind | null
+  labelOverride: string | null
+}
+
+export type ReportComposerSortState = {
+  fieldCode: string
+  groupKey?: string | null
+  appliesToColumnAxis?: boolean
+  direction: ReportSortDirection
+  timeGrain: ReportTimeGrain | null
+}
+
+export type ReportComposerDraft = {
+  parameters: Record<string, string>
+  filters: Record<string, ReportComposerFilterState>
+  rowGroups: ReportComposerGroupingState[]
+  columnGroups: ReportComposerGroupingState[]
+  measures: ReportComposerMeasureState[]
+  detailFields: string[]
+  sorts: ReportComposerSortState[]
+  showDetails: boolean
+  showSubtotals: boolean
+  showSubtotalsOnSeparateRows: boolean
+  showGrandTotals: boolean
+}
+
+export type ReportOptionItem<T extends string | number = string | number> = {
+  value: T
+  label: string
+}

package/src/ngb/router/backNavigation.ts

@@ -0,0 +1,122 @@
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router';
+
+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 encodeBase64Url(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = '';
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+function decodeBase64Url(value: string): string | null {
+  try {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((value.length + 3) % 4);
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+export function encodeBackTarget(target: string | null | undefined): string | null {
+  const normalized = String(target ?? '').trim();
+  if (!normalized) return null;
+  return encodeBase64Url(normalized);
+}
+
+export function decodeBackTarget(value: unknown): string | null {
+  const normalized = normalizeQueryValue(value);
+  if (!normalized) return null;
+  return decodeBase64Url(normalized);
+}
+
+function parseRouteTarget(target: string | null | undefined): URL | null {
+  const normalized = String(target ?? '').trim();
+  if (!normalized) return null;
+
+  try {
+    // Provide a synthetic absolute base only so the URL constructor can parse app-relative routes
+    // like "/documents/...". This value is never used for network requests and should not represent
+    // a real environment or host.
+    return new URL(normalized, 'http://ngb.local');
+  } catch {
+    return null;
+  }
+}
+
+export function resolveBackTargetFromPath(target: string | null | undefined): string | null {
+  const parsed = parseRouteTarget(target);
+  if (!parsed) return null;
+  return decodeBackTarget(parsed.searchParams.get('back'));
+}
+
+export function routeTargetMatches(
+  candidate: string | null | undefined,
+  expected: string | null | undefined,
+): boolean {
+  const parsedCandidate = parseRouteTarget(candidate);
+  const parsedExpected = parseRouteTarget(expected);
+  if (!parsedCandidate || !parsedExpected) return false;
+  if (parsedCandidate.pathname !== parsedExpected.pathname) return false;
+
+  for (const [key, value] of parsedExpected.searchParams.entries()) {
+    if (parsedCandidate.searchParams.get(key) !== value) return false;
+  }
+
+  return true;
+}
+
+export function buildPathWithQuery(path: string, patch: Record<string, string | null | undefined>): string {
+  const [pathname, rawQuery = ''] = path.split('?', 2);
+  const query = new URLSearchParams(rawQuery);
+
+  Object.entries(patch).forEach(([key, value]) => {
+    const normalized = String(value ?? '').trim();
+    if (normalized.length === 0) query.delete(key);
+    else query.set(key, normalized);
+  });
+
+  const suffix = query.toString();
+  return suffix ? `${pathname}?${suffix}` : pathname;
+}
+
+export function withBackTarget(path: string, backTarget: string | null | undefined): string {
+  const encoded = encodeBackTarget(backTarget);
+  return buildPathWithQuery(path, { back: encoded });
+}
+
+export function currentRouteBackTarget(route: Pick<RouteLocationNormalizedLoaded, 'fullPath'>): string {
+  return String(route.fullPath ?? '').trim() || '/';
+}
+
+export function resolveBackTarget(route: Pick<RouteLocationNormalizedLoaded, 'query'>): string | null {
+  return decodeBackTarget(route.query?.back);
+}
+
+export async function navigateBack(
+  router: Router,
+  route: Pick<RouteLocationNormalizedLoaded, 'query'>,
+  fallback?: string | null,
+): Promise<void> {
+  const explicit = resolveBackTarget(route);
+  if (explicit) {
+    await router.replace(explicit);
+    return;
+  }
+
+  const normalizedFallback = String(fallback ?? '').trim();
+  if (normalizedFallback.length > 0 && typeof window !== 'undefined' && window.history.length <= 1) {
+    await router.replace(normalizedFallback);
+    return;
+  }
+
+  router.back();
+}

package/src/ngb/router/queryParams.ts

@@ -0,0 +1,129 @@
+import {
+  type LocationQueryRaw,
+  type RouteLocationNormalizedLoaded,
+  type Router,
+} from 'vue-router'
+import {
+  normalizeDateOnlyValue as normalizeSharedDateOnlyValue,
+  normalizeMonthValue as normalizeSharedMonthValue,
+} from '../utils/dateValues'
+
+export type QueryTrashMode = 'active' | 'deleted' | 'all'
+export type QueryPatch = Record<string, unknown>
+export type QueryNavigationMode = 'push' | 'replace'
+
+export function normalizeTrashMode(value: unknown): QueryTrashMode {
+  const normalized = String(value ?? '').toLowerCase()
+  if (normalized === 'deleted') return 'deleted'
+  if (normalized === 'all') return 'all'
+  return 'active'
+}
+
+export function normalizeMonthValue(value: unknown): string {
+  return normalizeSharedMonthValue(value) ?? ''
+}
+
+export function normalizeMonthQueryValue(value: unknown): string | null {
+  const normalized = normalizeMonthValue(value)
+  return normalized || null
+}
+
+export function normalizeDateOnlyQueryValue(value: unknown): string | null {
+  const normalized = normalizeSingleQueryValue(value)
+  return normalizeSharedDateOnlyValue(normalized)
+}
+
+export function normalizeYearQueryValue(value: unknown): number | null {
+  const normalized = normalizeSingleQueryValue(value)
+  const parsed = Number.parseInt(normalized, 10)
+  return Number.isInteger(parsed) && parsed >= 1900 && parsed <= 9999 ? parsed : null
+}
+
+export function normalizeSingleQueryValue(value: unknown): string {
+  if (Array.isArray(value)) return String(value[0] ?? '').trim()
+  return String(value ?? '').trim()
+}
+
+export function firstQueryValue(value: unknown): string | null {
+  const normalized = normalizeSingleQueryValue(value)
+  return normalized.length > 0 ? normalized : null
+}
+
+export function normalizeBooleanQueryFlag(value: unknown): boolean {
+  const normalized = normalizeSingleQueryValue(value).toLowerCase()
+  return normalized === '1' || normalized === 'true' || normalized === 'yes'
+}
+
+export function normalizeAllowedQueryValue<TValue extends string>(
+  value: unknown,
+  allowedValues: readonly TValue[],
+): TValue | null {
+  const normalized = normalizeSingleQueryValue(value)
+  if (!normalized) return null
+
+  const allowed = new Set<string>(allowedValues)
+  return allowed.has(normalized) ? normalized as TValue : null
+}
+
+export function cleanQueryObject<T extends Record<string, unknown>>(query: T): T {
+  const next = { ...query }
+  for (const key of Object.keys(next)) {
+    if (next[key] == null || next[key] === '') delete next[key]
+  }
+  return next
+}
+
+export function mergeCleanQuery<TBase extends Record<string, unknown>, TPatch extends Record<string, unknown>>(
+  base: TBase,
+  patch: TPatch,
+): TBase & TPatch {
+  return cleanQueryObject({ ...base, ...patch })
+}
+
+export function navigateCleanRouteQuery(
+  route: RouteLocationNormalizedLoaded,
+  router: Router,
+  patch: QueryPatch,
+  mode: QueryNavigationMode = 'replace',
+) {
+  return setCleanRouteQuery(route, router, { ...route.query, ...patch }, mode)
+}
+
+export function setCleanRouteQuery(
+  route: RouteLocationNormalizedLoaded,
+  router: Router,
+  query: Record<string, unknown>,
+  mode: QueryNavigationMode = 'replace',
+) {
+  const nextQuery = cleanQueryObject({ ...query }) as LocationQueryRaw
+  return mode === 'push'
+    ? router.push({ path: route.path, query: nextQuery })
+    : router.replace({ path: route.path, query: nextQuery })
+}
+
+export function replaceCleanRouteQuery(
+  route: RouteLocationNormalizedLoaded,
+  router: Router,
+  patch: QueryPatch,
+) {
+  return navigateCleanRouteQuery(route, router, patch, 'replace')
+}
+
+export function pushCleanRouteQuery(
+  route: RouteLocationNormalizedLoaded,
+  router: Router,
+  patch: QueryPatch,
+) {
+  return navigateCleanRouteQuery(route, router, patch, 'push')
+}
+
+export function omitRouteQueryKeys(
+  route: RouteLocationNormalizedLoaded,
+  router: Router,
+  keys: readonly string[],
+  mode: QueryNavigationMode = 'replace',
+) {
+  const next = { ...route.query } as QueryPatch
+  for (const key of keys) delete next[key]
+  return setCleanRouteQuery(route, router, next, mode)
+}

package/src/ngb/router/queryState.ts

@@ -0,0 +1,121 @@
+import { computed, ref, watch, type WatchSource } from 'vue'
+import type { RouteLocationNormalizedLoaded, RouteLocationRaw, Router } from 'vue-router'
+
+import type { UiLookupItem } from '../lookup/store'
+import { isNonEmptyGuid } from '../utils/guid'
+import {
+  firstQueryValue,
+  normalizeAllowedQueryValue,
+  normalizeBooleanQueryFlag,
+  replaceCleanRouteQuery,
+  type QueryPatch,
+} from './queryParams'
+
+export type UseRouteQueryMigrationArgs<TValues extends readonly unknown[]> = {
+  route: RouteLocationNormalizedLoaded
+  router: Router
+  sources: WatchSource<TValues>
+  migrate: (values: TValues) => QueryPatch | null
+}
+
+export function useRouteQueryMigration<TValues extends readonly unknown[]>(
+  args: UseRouteQueryMigrationArgs<TValues>,
+) {
+  watch(
+    args.sources,
+    (values) => {
+      const patch = args.migrate(values)
+      if (!patch) return
+      void replaceCleanRouteQuery(args.route, args.router, patch)
+    },
+    { immediate: true },
+  )
+}
+
+export function useGuidQueryParam(
+  route: RouteLocationNormalizedLoaded,
+  key: string,
+) {
+  return computed(() => {
+    const value = firstQueryValue(route.query[key])
+    return isNonEmptyGuid(value) ? value : null
+  })
+}
+
+export function useBooleanQueryFlag(
+  route: RouteLocationNormalizedLoaded,
+  key: string,
+) {
+  return computed(() => normalizeBooleanQueryFlag(route.query[key]))
+}
+
+export function useAllowedQueryValue<TValue extends string>(
+  route: RouteLocationNormalizedLoaded,
+  key: string,
+  allowedValues: readonly TValue[],
+) {
+  return computed<TValue | null>(() => normalizeAllowedQueryValue(route.query[key], allowedValues))
+}
+
+export type UseRouteLookupSelectionArgs<TItem extends UiLookupItem = UiLookupItem> = {
+  route: RouteLocationNormalizedLoaded
+  router: Router
+  queryKey: string
+  lookupById: (id: string) => Promise<string | null | undefined>
+  search: (query: string) => Promise<TItem[]>
+  openTarget: (value: TItem | null) => Promise<RouteLocationRaw | null>
+}
+
+export function useRouteLookupSelection<TItem extends UiLookupItem = UiLookupItem>(
+  args: UseRouteLookupSelectionArgs<TItem>,
+) {
+  const selected = ref<TItem | null>(null)
+  const items = ref<TItem[]>([])
+  const routeId = useGuidQueryParam(args.route, args.queryKey)
+
+  async function hydrateSelected(): Promise<void> {
+    const id = routeId.value
+    if (!id) {
+      selected.value = null
+      return
+    }
+
+    try {
+      const label = await args.lookupById(id)
+      selected.value = { id, label: label ?? id } as TItem
+    } catch {
+      selected.value = { id, label: id } as TItem
+    }
+  }
+
+  async function onQuery(queryText: string): Promise<void> {
+    const query = queryText.trim()
+    if (!query) {
+      items.value = []
+      return
+    }
+
+    items.value = await args.search(query)
+  }
+
+  function onSelect(value: TItem | null): void {
+    selected.value = value
+    void replaceCleanRouteQuery(args.route, args.router, { [args.queryKey]: value?.id ?? null })
+  }
+
+  async function openSelected(): Promise<void> {
+    const target = await args.openTarget(selected.value)
+    if (!target) return
+    await args.router.push(target)
+  }
+
+  return {
+    selected,
+    items,
+    routeId,
+    hydrateSelected,
+    onQuery,
+    onSelect,
+    openSelected,
+  }
+}