@ngbplatform/ui 1.3.0

package/src/ngb/editor/documentNavigation.ts

@@ -0,0 +1,115 @@
+import type { RouteLocationNormalizedLoaded } from 'vue-router';
+
+import type { DocumentTypeMetadata, FormMetadata } from '../metadata/types';
+import {
+  currentRouteBackTarget,
+  resolveBackTarget,
+  resolveBackTargetFromPath,
+  routeTargetMatches,
+  withBackTarget,
+} from '../router/backNavigation';
+import { resolveNgbEditorRouting } from './config';
+import type { EditorKind, EditorMode } from './types';
+
+type FormFieldDescriptor = {
+  key?: string;
+  isReadOnly?: boolean;
+};
+
+type FormShape = {
+  sections?: Array<{
+    rows?: Array<{
+      fields?: FormFieldDescriptor[];
+    }>;
+  }>;
+} | null | undefined;
+
+export function documentHasTables(meta: DocumentTypeMetadata | null | undefined): boolean {
+  return Array.isArray(meta?.parts) && meta.parts.length > 0;
+}
+
+export function shouldOpenDocumentInFullPageByDefault(meta: DocumentTypeMetadata | null | undefined): boolean {
+  return documentHasTables(meta);
+}
+
+export function buildDocumentFullPageUrl(documentType: string, id?: string | null): string {
+  return resolveNgbEditorRouting().buildDocumentFullPageUrl(documentType, id);
+}
+
+export function buildDocumentCompactPageUrl(documentType: string, id?: string | null): string {
+  return resolveNgbEditorRouting().buildDocumentCompactPageUrl(documentType, id);
+}
+
+export function buildDocumentEffectsPageUrl(documentType: string, id: string): string {
+  return resolveNgbEditorRouting().buildDocumentEffectsPageUrl(documentType, id);
+}
+
+export function buildDocumentFlowPageUrl(documentType: string, id: string): string {
+  return resolveNgbEditorRouting().buildDocumentFlowPageUrl(documentType, id);
+}
+
+export function buildDocumentPrintPageUrl(
+  documentType: string,
+  id: string,
+  options?: { autoPrint?: boolean },
+): string {
+  return resolveNgbEditorRouting().buildDocumentPrintPageUrl(documentType, id, options);
+}
+
+export function resolveCompactDocumentSourceTarget(
+  route: Pick<RouteLocationNormalizedLoaded, 'query'>,
+  compactTarget: string | null | undefined,
+): string | null {
+  const explicitBack = resolveBackTarget(route);
+  if (routeTargetMatches(explicitBack, compactTarget)) return explicitBack;
+
+  const nestedBack = resolveBackTargetFromPath(explicitBack);
+  if (routeTargetMatches(nestedBack, compactTarget)) return nestedBack;
+
+  return null;
+}
+
+export function resolveDocumentReopenTarget(
+  route: Pick<RouteLocationNormalizedLoaded, 'query' | 'fullPath'>,
+  documentType: string,
+  id: string,
+  compactTarget?: string | null,
+): string {
+  const compactSourceTarget = resolveCompactDocumentSourceTarget(
+    route,
+    compactTarget ?? buildDocumentCompactPageUrl(documentType, id),
+  );
+  if (compactSourceTarget) return compactSourceTarget;
+
+  const explicitBack = resolveBackTarget(route);
+  if (explicitBack) return explicitBack;
+
+  return withBackTarget(
+    buildDocumentFullPageUrl(documentType, id),
+    currentRouteBackTarget(route),
+  );
+}
+
+export function buildEntityFallbackCloseTarget(kind: EditorKind, typeCode: string): string {
+  return `${kind === 'catalog' ? '/catalogs/' : '/documents/'}${typeCode}`;
+}
+
+export function resolveNavigateOnCreate(value: boolean | undefined, mode: EditorMode): boolean {
+  return value ?? mode === 'page';
+}
+
+export function listFormFields(form: FormShape): FormFieldDescriptor[] {
+  const out: FormFieldDescriptor[] = [];
+  for (const section of form?.sections ?? []) {
+    for (const row of section.rows ?? []) {
+      for (const field of row.fields ?? []) out.push(field);
+    }
+  }
+  return out;
+}
+
+export function formMetadataFieldKeys(form: FormMetadata | null | undefined): string[] {
+  return listFormFields(form)
+    .map((field) => String(field?.key ?? '').trim())
+    .filter((key) => key.length > 0);
+}

package/src/ngb/editor/documentStatus.ts

@@ -0,0 +1,45 @@
+import type { DocumentStatusValue } from '../metadata/types';
+
+export type DocumentStatusTone = 'neutral' | 'success' | 'warn';
+export type DocumentStatusVisual = 'saved' | 'posted' | 'marked';
+
+export function normalizeDocumentStatusValue(value: unknown): DocumentStatusValue {
+  if (typeof value === 'number' && Number.isFinite(value) && (value === 1 || value === 2 || value === 3)) {
+    return value as DocumentStatusValue;
+  }
+
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (normalized === '1' || normalized === 'draft') return 1;
+  if (normalized === '2' || normalized === 'posted') return 2;
+  if (
+    normalized === '3'
+    || normalized === 'deleted'
+    || normalized === 'markedfordeletion'
+    || normalized === 'marked_for_deletion'
+    || normalized === 'marked-for-deletion'
+    || normalized === 'marked for deletion'
+  ) return 3;
+
+  return 1;
+}
+
+export function documentStatusLabel(value: unknown): string {
+  const status = normalizeDocumentStatusValue(value);
+  if (status === 2) return 'Posted';
+  if (status === 3) return 'Deleted';
+  return 'Draft';
+}
+
+export function documentStatusTone(value: unknown): DocumentStatusTone {
+  const status = normalizeDocumentStatusValue(value);
+  if (status === 2) return 'success';
+  if (status === 3) return 'warn';
+  return 'neutral';
+}
+
+export function documentStatusVisual(value: unknown): DocumentStatusVisual {
+  const status = normalizeDocumentStatusValue(value);
+  if (status === 2) return 'posted';
+  if (status === 3) return 'marked';
+  return 'saved';
+}

package/src/ngb/editor/entityEditorErrors.ts

@@ -0,0 +1,162 @@
+import { ApiError, type ApiValidationIssue } from '../api/http';
+
+export const ENTITY_EDITOR_FORM_ISSUE_PATH = '_form';
+
+export type EditorErrorIssue = {
+  path: string;
+  label: string;
+  scope: string;
+  messages: string[];
+  code?: string | null;
+};
+
+export type EditorErrorState = {
+  summary: string;
+  issues: EditorErrorIssue[];
+  errorCode?: string | null;
+  status?: number | null;
+  context?: Record<string, unknown> | null;
+};
+
+export type NormalizeEntityEditorErrorOptions = {
+  resolveIssueLabel?: (path: string) => string;
+};
+
+export function dedupeEntityEditorMessages(messages: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const message of messages) {
+    const value = String(message ?? '').trim();
+    if (!value) continue;
+
+    const key = value.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(value);
+  }
+
+  return result;
+}
+
+export function humanizeEntityEditorFieldKey(key: string): string {
+  const base = String(key ?? '').trim();
+  if (!base) return 'Field';
+
+  const normalized = base
+    .replace(/_utc$/i, '')
+    .replace(/_id$/i, '')
+    .replace(/[._]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  const words = normalized.split(' ').filter(Boolean).map((word) => {
+    const lower = word.toLowerCase();
+    if (lower === 'no') return 'No';
+    if (lower === 'id') return 'ID';
+    if (/^line\d+$/i.test(word)) return `Line ${word.slice(4)}`;
+    return lower.charAt(0).toUpperCase() + lower.slice(1);
+  });
+
+  return words.join(' ') || 'Field';
+}
+
+export function isEntityEditorFormIssuePath(path: string): boolean {
+  const raw = String(path ?? '').trim();
+  return raw.length === 0 || raw === ENTITY_EDITOR_FORM_ISSUE_PATH;
+}
+
+function defaultEditorIssueLabel(path: string): string {
+  if (isEntityEditorFormIssuePath(path)) return 'Validation';
+  return humanizeEntityEditorFieldKey(path);
+}
+
+function buildEditorIssuesFromApiIssues(
+  issues: ApiValidationIssue[],
+  resolveIssueLabel: (path: string) => string,
+): EditorErrorIssue[] {
+  const buckets = new Map<string, EditorErrorIssue>();
+
+  for (const issue of issues) {
+    const path = String(issue.path ?? '').trim() || ENTITY_EDITOR_FORM_ISSUE_PATH;
+    const scope = String(issue.scope ?? '').trim() || (isEntityEditorFormIssuePath(path) ? 'form' : 'field');
+    const message = String(issue.message ?? '').trim();
+    if (!message) continue;
+
+    const bucketKey = `${scope}:${path}`;
+    const current = buckets.get(bucketKey) ?? {
+      path,
+      label: resolveIssueLabel(path),
+      scope,
+      messages: [],
+      code: issue.code ?? null,
+    };
+
+    current.messages = dedupeEntityEditorMessages([...current.messages, message]);
+    if (!current.code && issue.code) current.code = issue.code;
+    buckets.set(bucketKey, current);
+  }
+
+  return Array.from(buckets.values());
+}
+
+function buildEditorIssuesFromLegacyErrors(
+  rawErrors: Record<string, string[] | string>,
+  resolveIssueLabel: (path: string) => string,
+): EditorErrorIssue[] {
+  const issues: EditorErrorIssue[] = [];
+
+  for (const [path, values] of Object.entries(rawErrors)) {
+    const messages = dedupeEntityEditorMessages(Array.isArray(values) ? values : [String(values)]);
+    if (messages.length === 0) continue;
+
+    issues.push({
+      path,
+      label: resolveIssueLabel(path),
+      scope: isEntityEditorFormIssuePath(path) ? 'form' : 'field',
+      messages,
+      code: null,
+    });
+  }
+
+  return issues;
+}
+
+export function resolveEntityEditorErrorSummary(summary: string, issues: EditorErrorIssue[]): string {
+  const fallback = summary.trim() || 'Request failed.';
+  const hasHighlightableIssues = issues.some((issue) => !isEntityEditorFormIssuePath(issue.path));
+  if (hasHighlightableIssues) return 'Please fix the highlighted fields.';
+  return fallback;
+}
+
+export function normalizeEntityEditorError(
+  cause: unknown,
+  options: NormalizeEntityEditorErrorOptions = {},
+): EditorErrorState {
+  const resolveIssueLabel = options.resolveIssueLabel ?? defaultEditorIssueLabel;
+
+  if (cause instanceof ApiError) {
+    const issues = cause.issues && cause.issues.length > 0
+      ? buildEditorIssuesFromApiIssues(cause.issues, resolveIssueLabel)
+      : cause.errors
+        ? buildEditorIssuesFromLegacyErrors(cause.errors, resolveIssueLabel)
+        : [];
+
+    return {
+      summary: resolveEntityEditorErrorSummary(String(cause.message ?? '').trim(), issues),
+      issues,
+      errorCode: cause.errorCode ?? null,
+      status: cause.status,
+      context: cause.context ?? null,
+    };
+  }
+
+  const summary = cause instanceof Error ? cause.message : String(cause ?? 'Request failed.');
+  return {
+    summary: summary.trim() || 'Request failed.',
+    issues: [],
+    errorCode: null,
+    status: null,
+    context: null,
+  };
+}

package/src/ngb/editor/entityEditorPersistence.ts

@@ -0,0 +1,241 @@
+import type { ComputedRef, Ref } from 'vue';
+
+import type { EntityFormModel, RecordPayload } from '../metadata/types';
+import type { ToastApi as SharedToastApi } from '../primitives/toast';
+import { clonePlainData } from '../utils/clone';
+import type { EditorChangeReason, EditorKind } from './types';
+import type { EditorErrorState } from './entityEditorErrors';
+
+type EntityEditorMetadataWithForm = {
+  form?: unknown | null;
+};
+
+export type EntityEditorToastApi = Pick<SharedToastApi, 'push'>;
+
+export type EntityEditorMetadataStoreLike<TCatalogMeta, TDocumentMeta> = {
+  ensureCatalogType: (typeCode: string) => Promise<TCatalogMeta>;
+  ensureDocumentType: (typeCode: string) => Promise<TDocumentMeta>;
+};
+
+export type CatalogEntityPersistenceAdapter = {
+  load: () => Promise<void>;
+  save: () => Promise<void>;
+  markForDeletion: () => Promise<void>;
+  unmarkForDeletion: () => Promise<void>;
+  deleteEntity: () => Promise<void>;
+};
+
+export type DocumentEntityPersistenceAdapter = {
+  load: () => Promise<void>;
+  save: () => Promise<void>;
+  markForDeletion: () => Promise<void>;
+  unmarkForDeletion: () => Promise<void>;
+  post: () => Promise<void>;
+  unpost: () => Promise<void>;
+  loadEffectsSnapshot?: (documentType: string, id: string) => Promise<void>;
+};
+
+export type UseEntityEditorPersistenceArgs<
+  TMetadata extends EntityEditorMetadataWithForm = EntityEditorMetadataWithForm,
+> = {
+  kind: ComputedRef<EditorKind>;
+  typeCode: ComputedRef<string>;
+  metadata: ComputedRef<TMetadata | null>;
+  loading: Ref<boolean>;
+  saving: Ref<boolean>;
+  canSave: ComputedRef<boolean>;
+  canMarkForDeletion: ComputedRef<boolean>;
+  canUnmarkForDeletion: ComputedRef<boolean>;
+  canDelete: ComputedRef<boolean>;
+  canPost: ComputedRef<boolean>;
+  canUnpost: ComputedRef<boolean>;
+  isNew: ComputedRef<boolean>;
+  isDirty: ComputedRef<boolean>;
+  error: Ref<EditorErrorState | null>;
+  setEditorError: (value: EditorErrorState | null) => void;
+  normalizeEditorError: (cause: unknown) => EditorErrorState;
+  emitChanged: (reason?: EditorChangeReason) => void;
+  emitDeleted: () => void;
+  adapters: {
+    catalog: CatalogEntityPersistenceAdapter;
+    document: DocumentEntityPersistenceAdapter;
+  };
+};
+
+export function applyInitialFieldValues(target: EntityFormModel, source: EntityFormModel | null) {
+  if (!source) return;
+
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    target[key] = clonePlainData(value);
+  }
+}
+
+export function setModelFromFields(
+  target: Ref<EntityFormModel>,
+  fields: RecordPayload['fields'] | null | undefined,
+) {
+  target.value = { ...((fields ?? {}) as EntityFormModel) };
+}
+
+export function useEntityEditorPersistence<
+  TMetadata extends EntityEditorMetadataWithForm = EntityEditorMetadataWithForm,
+>(args: UseEntityEditorPersistenceArgs<TMetadata>) {
+  async function load() {
+    if (!args.typeCode.value) return;
+
+    args.loading.value = true;
+    args.setEditorError(null);
+
+    try {
+      if (args.kind.value === 'catalog') {
+        await args.adapters.catalog.load();
+        return;
+      }
+
+      await args.adapters.document.load();
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.loading.value = false;
+    }
+  }
+
+  async function save() {
+    if (!args.metadata.value?.form) return;
+    if (!args.canSave.value) return;
+
+    args.saving.value = true;
+    args.setEditorError(null);
+
+    try {
+      if (args.kind.value === 'catalog') {
+        await args.adapters.catalog.save();
+        return;
+      }
+
+      await args.adapters.document.save();
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function markForDeletion() {
+    if (args.isNew.value || !args.canMarkForDeletion.value) return;
+
+    args.saving.value = true;
+    args.setEditorError(null);
+
+    try {
+      if (args.kind.value === 'catalog') {
+        await args.adapters.catalog.markForDeletion();
+      } else {
+        await args.adapters.document.markForDeletion();
+      }
+
+      await load();
+      args.emitChanged('markForDeletion');
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function unmarkForDeletion() {
+    if (args.isNew.value || !args.canUnmarkForDeletion.value) return;
+
+    args.saving.value = true;
+    args.setEditorError(null);
+
+    try {
+      if (args.kind.value === 'catalog') {
+        await args.adapters.catalog.unmarkForDeletion();
+      } else {
+        await args.adapters.document.unmarkForDeletion();
+      }
+
+      await load();
+      args.emitChanged('unmarkForDeletion');
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function deleteEntity() {
+    if (args.kind.value !== 'catalog' || args.isNew.value || !args.canDelete.value) return;
+
+    args.saving.value = true;
+    args.setEditorError(null);
+
+    try {
+      await args.adapters.catalog.deleteEntity();
+      await load();
+      args.emitDeleted();
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function post() {
+    if (!args.canPost.value) return;
+
+    args.setEditorError(null);
+
+    if (args.isDirty.value) {
+      await save();
+      if (args.error.value) return;
+      if (!args.canPost.value) return;
+    }
+
+    args.saving.value = true;
+
+    try {
+      await args.adapters.document.post();
+      await load();
+      args.emitChanged('post');
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function unpost() {
+    if (!args.canUnpost.value) return;
+
+    args.saving.value = true;
+    args.setEditorError(null);
+
+    try {
+      await args.adapters.document.unpost();
+      await load();
+      args.emitChanged('unpost');
+    } catch (cause) {
+      args.setEditorError(args.normalizeEditorError(cause));
+    } finally {
+      args.saving.value = false;
+    }
+  }
+
+  async function loadDocumentEffectsSnapshot(documentType: string, id: string) {
+    await args.adapters.document.loadEffectsSnapshot?.(documentType, id);
+  }
+
+  return {
+    load,
+    save,
+    markForDeletion,
+    unmarkForDeletion,
+    deleteEntity,
+    post,
+    unpost,
+    loadDocumentEffectsSnapshot,
+  };
+}

package/src/ngb/editor/extensions.ts

@@ -0,0 +1,40 @@
+import type { Component, ComputedRef } from 'vue';
+
+import type { Awaitable } from '../metadata/types';
+import type { EditorKind, EditorMode, EntityHeaderIconAction } from './types';
+
+export type EntityEditorRenderExtension = {
+  key: string;
+  component: Component;
+  props?: Record<string, unknown>;
+  componentRef?: ((value: unknown) => void) | null;
+};
+
+export type EntityEditorActionHandler = () => Awaitable<void>;
+export type EntityEditorActionHandlerMap = Record<string, EntityEditorActionHandler | undefined>;
+
+export type UseEntityEditorPageActionsArgs = {
+  kind: ComputedRef<EditorKind>;
+  mode: ComputedRef<EditorMode>;
+  compactTo: ComputedRef<string | null>;
+  loading: ComputedRef<boolean>;
+  saving: ComputedRef<boolean>;
+  isNew: ComputedRef<boolean>;
+  isMarkedForDeletion: ComputedRef<boolean>;
+  canSave: ComputedRef<boolean>;
+  canShareLink: ComputedRef<boolean>;
+  canOpenAudit: ComputedRef<boolean>;
+  canMarkForDeletion: ComputedRef<boolean>;
+  canUnmarkForDeletion: ComputedRef<boolean>;
+  extraActions?: ComputedRef<EntityHeaderIconAction[]>;
+};
+
+export function runEntityEditorAction(
+  action: string,
+  handlers: EntityEditorActionHandlerMap,
+): boolean {
+  const handler = handlers[action];
+  if (!handler) return false;
+  void Promise.resolve(handler());
+  return true;
+}