@ngbplatform/ui 1.3.0

package/src/ngb/editor/types.ts

@@ -0,0 +1,295 @@
+import type { NgbIconName } from '../primitives/iconNames';
+import type {
+  DocumentStatusValue,
+  LookupHint,
+  LookupSource,
+  LookupStoreApi,
+  RecordPayload,
+} from '../metadata/types';
+
+export type EditorKind = 'catalog' | 'document';
+export type EditorMode = 'page' | 'drawer';
+export type EditorChangeReason = 'markForDeletion' | 'unmarkForDeletion' | 'post' | 'unpost';
+
+export type EntityEditorContext = {
+  kind: EditorKind;
+  typeCode: string;
+};
+
+export type EntityEditorFlags = {
+  canSave: boolean;
+  isDirty: boolean;
+  loading: boolean;
+  saving: boolean;
+  canExpand: boolean;
+  canDelete: boolean;
+  canMarkForDeletion: boolean;
+  canUnmarkForDeletion: boolean;
+  canPost: boolean;
+  canUnpost: boolean;
+  canShowAudit: boolean;
+  canShareLink: boolean;
+  extras?: Record<string, boolean | undefined>;
+};
+
+export type EntityHeaderIconAction = {
+  key: string;
+  title: string;
+  icon: NgbIconName;
+  disabled?: boolean;
+};
+
+export type DocumentHeaderCoreActionKey =
+  | 'openCompactPage'
+  | 'openFullPage'
+  | 'copyDocument'
+  | 'printDocument'
+  | 'toggleMarkForDeletion'
+  | 'save'
+  | 'togglePost'
+  | 'openEffectsPage'
+  | 'openDocumentFlowPage'
+  | 'openAuditLog'
+  | 'copyShareLink';
+
+export type DocumentHeaderActionKey = DocumentHeaderCoreActionKey | (string & {});
+
+export type DocumentHeaderActionItem = {
+  key: DocumentHeaderActionKey;
+  title: string;
+  icon: NgbIconName;
+  disabled?: boolean;
+};
+
+export type DocumentHeaderActionGroup = {
+  key: string;
+  label: string;
+  items: DocumentHeaderActionItem[];
+};
+
+export type DocumentRecord = {
+  id: string;
+  number?: string | null;
+  display?: string | null;
+  payload: RecordPayload;
+  status: DocumentStatusValue;
+  isMarkedForDeletion?: boolean;
+};
+
+export type RelationshipGraphNode = {
+  nodeId: string;
+  kind: number;
+  typeCode: string;
+  entityId: string;
+  title: string;
+  subtitle?: string | null;
+  documentStatus?: DocumentStatusValue | null;
+  depth?: number | null;
+  amount?: number | null;
+};
+
+export type RelationshipGraphEdge = {
+  fromNodeId: string;
+  toNodeId: string;
+  relationshipType: string;
+  label?: string | null;
+};
+
+export type RelationshipGraph = {
+  nodes: RelationshipGraphNode[];
+  edges: RelationshipGraphEdge[];
+};
+
+export type EffectAccount = {
+  accountId: string;
+  code: string;
+  name: string;
+};
+
+export type EffectDimensionValue = {
+  dimensionId: string;
+  valueId: string;
+  display: string;
+};
+
+export type EffectResourceValue = {
+  code: string;
+  value: number;
+};
+
+export type AccountingEntryEffect = {
+  entryId: string | number;
+  documentId?: string | null;
+  occurredAtUtc: string;
+  debitAccount?: EffectAccount | null;
+  creditAccount?: EffectAccount | null;
+  debitAccountId?: string | null;
+  creditAccountId?: string | null;
+  amount: number;
+  isStorno?: boolean;
+  debitDimensionSetId?: string | null;
+  creditDimensionSetId?: string | null;
+  debitDimensions?: EffectDimensionValue[] | null;
+  creditDimensions?: EffectDimensionValue[] | null;
+};
+
+export type OperationalRegisterMovementEffect = {
+  registerId?: string | null;
+  registerCode: string;
+  registerName?: string | null;
+  movementId: string | number;
+  documentId?: string | null;
+  occurredAtUtc: string;
+  periodMonth?: string | null;
+  isStorno?: boolean;
+  dimensionSetId?: string | null;
+  dimensions?: EffectDimensionValue[] | null;
+  resources: EffectResourceValue[] | Record<string, unknown>;
+};
+
+export type ReferenceRegisterWriteEffect = {
+  registerId?: string | null;
+  registerCode: string;
+  registerName?: string | null;
+  recordId: string | number;
+  documentId?: string | null;
+  periodUtc?: string | null;
+  periodBucketUtc?: string | null;
+  recordedAtUtc: string;
+  dimensionSetId?: string | null;
+  dimensions?: EffectDimensionValue[] | null;
+  fields: Record<string, unknown>;
+  isTombstone: boolean;
+};
+
+export type DocumentUiActionReason = {
+  errorCode: string;
+  message: string;
+};
+
+export type DocumentUiEffects = {
+  isPosted: boolean;
+  canEdit: boolean;
+  canPost: boolean;
+  canUnpost: boolean;
+  canRepost: boolean;
+  canApply: boolean;
+  disabledReasons?: Record<string, DocumentUiActionReason[]> | null;
+};
+
+export type DocumentEffects = {
+  accountingEntries: AccountingEntryEffect[];
+  operationalRegisterMovements: OperationalRegisterMovementEffect[];
+  referenceRegisterWrites: ReferenceRegisterWriteEffect[];
+  ui?: DocumentUiEffects | null;
+};
+
+export type EntityEditorHandle<TDocumentEffects = DocumentEffects | null> = {
+  save: () => Promise<void>;
+  load: () => Promise<void>;
+  openFullPage: () => void;
+  openCompactPage: () => void;
+  closePage: () => void;
+  toggleMarkForDeletion: () => void;
+  togglePost: () => void;
+  markForDeletion: () => Promise<void>;
+  unmarkForDeletion: () => Promise<void>;
+  deleteEntity: () => Promise<void>;
+  post: () => Promise<void>;
+  unpost: () => Promise<void>;
+  getDocumentEffects: () => TDocumentEffects;
+  reloadDocumentEffects: () => Promise<TDocumentEffects>;
+  copyShareLink: () => Promise<void>;
+  copyDocument: () => void;
+  printDocument: () => void;
+  openAuditLog: () => void;
+  openAudit: () => void;
+  closeAuditLog: () => void;
+  getIsDirty: () => boolean;
+  getCanSave: () => boolean;
+  getFlags: () => EntityEditorFlags;
+};
+
+export type AuditFieldChange = {
+  fieldPath: string;
+  oldValueJson?: string | null;
+  newValueJson?: string | null;
+};
+
+export type AuditActor = {
+  userId?: string | null;
+  displayName?: string | null;
+  email?: string | null;
+};
+
+export type AuditEvent = {
+  auditEventId: string;
+  entityKind: number;
+  entityId: string;
+  actionCode: string;
+  actor?: AuditActor | null;
+  occurredAtUtc: string;
+  correlationId?: string | null;
+  metadataJson?: string | null;
+  changes: AuditFieldChange[];
+};
+
+export type AuditCursor = {
+  occurredAtUtc: string;
+  auditEventId: string;
+};
+
+export type AuditLogPage = {
+  items: AuditEvent[];
+  nextCursor?: AuditCursor | null;
+  limit: number;
+};
+
+export type EditorAuditLoadOptions = {
+  afterOccurredAtUtc?: string | null;
+  afterAuditEventId?: string | null;
+  limit?: number;
+};
+
+export type EditorAuditBehavior = {
+  hiddenFieldNames?: string[];
+  explicitFieldLabels?: Record<string, string>;
+  actionTitles?: Record<string, string>;
+};
+
+export type EditorDocumentEffectsBehavior = {
+  prefetchRelatedLabels?: (args: {
+    documentType: string;
+    documentId: string;
+    effects: DocumentEffects;
+    lookupStore: LookupStoreApi | null;
+  }) => Promise<void> | void;
+  resolveAccountLabel?: (args: {
+    account: EffectAccount | null | undefined;
+    accountId: string | null | undefined;
+    lookupStore: LookupStoreApi | null;
+  }) => string;
+  resolveDimensionDisplay?: (args: {
+    item: EffectDimensionValue | null | undefined;
+    lookupStore: LookupStoreApi | null;
+  }) => string;
+  resolveFieldValue?: (args: {
+    documentType: string;
+    documentId: string;
+    document: DocumentRecord | null;
+    fieldKey: string;
+    value: unknown;
+    fields: Record<string, unknown>;
+    lookupStore: LookupStoreApi | null;
+  }) => string | null | undefined;
+};
+
+export type EditorPrintLookupHintArgs = {
+  documentType: string;
+  fieldKey: string;
+  lookup?: LookupSource | null;
+};
+
+export type EditorPrintBehavior = {
+  resolveLookupHint?: (args: EditorPrintLookupHintArgs) => LookupHint | null;
+};

package/src/ngb/editor/useConfiguredEntityEditorDocumentActions.ts

@@ -0,0 +1,183 @@
+import { computed, type ComputedRef, type Ref, ref, watch } from 'vue';
+
+import { getDocumentDerivationActions, deriveDocument } from '../api/documents';
+import type { DocumentDerivationActionDto } from '../api/contracts';
+import type { EntityFormModel } from '../metadata/types';
+import type { DocumentTypeMetadata } from '../metadata/types';
+import { resolveNgbEditorDocumentActions, resolveNgbEditorRouting } from './config';
+import type { EditorErrorState } from './entityEditorErrors';
+import type { DocumentHeaderActionGroup, DocumentHeaderActionItem, DocumentUiEffects, EditorKind } from './types';
+
+type DocumentMetadataStoreLike = {
+  ensureDocumentType: (documentType: string) => Promise<DocumentTypeMetadata>;
+};
+
+type UseConfiguredEntityEditorDocumentActionsArgs = {
+  kind: ComputedRef<EditorKind>;
+  typeCode: ComputedRef<string>;
+  currentId: ComputedRef<string | null>;
+  model: Ref<EntityFormModel>;
+  uiEffects: ComputedRef<DocumentUiEffects | null>;
+  loading: ComputedRef<boolean>;
+  saving: ComputedRef<boolean>;
+  requestNavigate: (to: string | null | undefined) => void;
+  metadataStore: DocumentMetadataStoreLike;
+  setEditorError: (value: EditorErrorState | null) => void;
+  normalizeEditorError: (cause: unknown) => EditorErrorState;
+  loadDerivationActions?: (documentType: string, id: string) => Promise<DocumentDerivationActionDto[]>;
+};
+
+export function useConfiguredEntityEditorDocumentActions(
+  args: UseConfiguredEntityEditorDocumentActionsArgs,
+) {
+  const configuredActions = computed(() => {
+    if (args.kind.value !== 'document') return [];
+    if (!args.currentId.value) return [];
+
+    return resolveNgbEditorDocumentActions({
+      context: {
+        kind: 'document',
+        typeCode: args.typeCode.value,
+      },
+      documentId: args.currentId.value,
+      model: args.model.value,
+      uiEffects: args.uiEffects.value,
+      loading: args.loading.value,
+      saving: args.saving.value,
+      navigate: args.requestNavigate,
+    });
+  });
+
+  const derivationActions = ref<DocumentDerivationActionDto[]>([]);
+  const derivationTitles = ref<Record<string, string>>({});
+  const loadDerivationActions = args.loadDerivationActions ?? getDocumentDerivationActions;
+
+  watch(
+    [args.kind, args.typeCode, args.currentId],
+    ([kind, typeCode, documentId], _, onCleanup) => {
+      derivationActions.value = [];
+      derivationTitles.value = {};
+
+      if (kind !== 'document' || !documentId) return;
+
+      let cancelled = false;
+      onCleanup(() => {
+        cancelled = true;
+      });
+
+      void (async () => {
+        try {
+          const actions = await loadDerivationActions(typeCode, documentId);
+          const titleEntries = await Promise.all(actions.map(async (action) => {
+            const title = await resolveDerivationTitle(args.metadataStore, action);
+            return [action.code, title] as const;
+          }));
+
+          if (cancelled) return;
+
+          derivationActions.value = actions;
+          derivationTitles.value = Object.fromEntries(titleEntries);
+        } catch {
+          if (cancelled) return;
+          derivationActions.value = [];
+          derivationTitles.value = {};
+        }
+      })();
+    },
+    { immediate: true },
+  );
+
+  const derivedCreateActions = computed(() =>
+    derivationActions.value
+      .map((action) => ({
+        action,
+        title: derivationTitles.value[action.code] ?? action.name,
+      }))
+      .sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }))
+      .map(({ action, title }) => ({
+        item: {
+          key: `derive:${action.code}`,
+          title,
+          icon: 'file-text' as const,
+          disabled: args.loading.value || args.saving.value,
+        },
+        group: {
+          key: 'create',
+          label: 'Create',
+        },
+        run: async () => {
+          const relationshipType = action.relationshipCodes
+            .map((value) => String(value ?? '').trim())
+            .find((value) => value.length > 0);
+
+          if (!relationshipType || !args.currentId.value) return;
+
+          const document = await deriveDocument(action.toTypeCode, {
+            sourceDocumentId: args.currentId.value,
+            relationshipType,
+          });
+
+          args.requestNavigate(resolveNgbEditorRouting().buildDocumentFullPageUrl(action.toTypeCode, document.id));
+        },
+      })));
+
+  const actions = computed(() => [...configuredActions.value, ...derivedCreateActions.value]);
+
+  const extraPrimaryActions = computed<DocumentHeaderActionItem[]>(() =>
+    actions.value
+      .filter((action) => !action.group)
+      .map((action) => action.item),
+  );
+
+  const extraMoreActionGroups = computed<DocumentHeaderActionGroup[]>(() => {
+    const buckets = new Map<string, DocumentHeaderActionGroup>();
+
+    for (const action of actions.value) {
+      if (!action.group) continue;
+
+      const current = buckets.get(action.group.key) ?? {
+        key: action.group.key,
+        label: action.group.label,
+        items: [],
+      };
+
+      current.items.push(action.item);
+      buckets.set(action.group.key, current);
+    }
+
+    return Array.from(buckets.values());
+  });
+
+  function handleConfiguredAction(actionKey: string): boolean {
+    const match = actions.value.find((action) => action.item.key === actionKey);
+    if (!match) return false;
+    if (match.item.disabled) return true;
+
+    args.setEditorError(null);
+    void Promise.resolve(match.run()).catch((cause) => {
+      args.setEditorError(args.normalizeEditorError(cause));
+    });
+    return true;
+  }
+
+  return {
+    extraPrimaryActions,
+    extraMoreActionGroups,
+    handleConfiguredAction,
+  };
+}
+
+async function resolveDerivationTitle(
+  metadataStore: DocumentMetadataStoreLike,
+  action: DocumentDerivationActionDto,
+): Promise<string> {
+  try {
+    const metadata = await metadataStore.ensureDocumentType(action.toTypeCode);
+    const title = String(metadata.displayName ?? '').trim();
+    if (title) return title;
+  } catch {
+    // Ignore metadata lookup failures and fall back to the derivation definition name.
+  }
+
+  return String(action.name ?? '').trim() || action.toTypeCode;
+}

package/src/ngb/editor/useDocumentEditorDrawerState.ts

@@ -0,0 +1,152 @@
+import { computed, ref, watch, type ComputedRef } from 'vue';
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router';
+
+import type { EntityFormModel, RecordPayload } from '../metadata/types';
+import { normalizeSingleQueryValue, replaceCleanRouteQuery } from '../router/queryParams';
+import { readDocumentCopyDraft, type DocumentCopyDraftSnapshot } from './documentCopyDraft';
+import { buildDocumentFullPageUrl } from './documentNavigation';
+
+export const DOCUMENT_EDITOR_DRAWER_QUERY_KEYS = ['panel', 'id', 'copyDraft'] as const;
+
+const DOCUMENT_EDITOR_DRAWER_QUERY_KEY_SET = new Set<string>(DOCUMENT_EDITOR_DRAWER_QUERY_KEYS);
+
+export type DocumentEditorDrawerMode = 'closed' | 'new' | 'edit';
+
+export type UseDocumentEditorDrawerStateArgs = {
+  route: RouteLocationNormalizedLoaded;
+  router: Router;
+  documentType: ComputedRef<string>;
+};
+
+export function isDocumentEditorDrawerQueryKey(key: string): boolean {
+  return DOCUMENT_EDITOR_DRAWER_QUERY_KEY_SET.has(String(key));
+}
+
+export function useDocumentEditorDrawerState(
+  args: UseDocumentEditorDrawerStateArgs,
+) {
+  const drawerMode = ref<DocumentEditorDrawerMode>('closed');
+  const drawerId = ref<string | null>(null);
+  const drawerCopyDraftToken = ref<string | null>(null);
+
+  const isPanelOpen = computed(() =>
+    drawerMode.value === 'new' || (drawerMode.value === 'edit' && !!drawerId.value),
+  );
+  const currentEditorId = computed(() =>
+    drawerMode.value === 'edit' ? drawerId.value : null,
+  );
+  const initialCopyDraft = computed<DocumentCopyDraftSnapshot | null>(() =>
+    drawerMode.value === 'new' && args.documentType.value
+      ? readDocumentCopyDraft(drawerCopyDraftToken.value, args.documentType.value)
+      : null,
+  );
+  const initialFields = computed<EntityFormModel | null>(() => initialCopyDraft.value?.fields ?? null);
+  const initialParts = computed<RecordPayload['parts'] | null>(() => initialCopyDraft.value?.parts ?? null);
+  const expandTo = computed(() => {
+    if (!args.documentType.value) return null;
+    if (drawerMode.value === 'new') return buildDocumentFullPageUrl(args.documentType.value);
+    if (currentEditorId.value) return buildDocumentFullPageUrl(args.documentType.value, currentEditorId.value);
+    return null;
+  });
+
+  function setDrawerState(
+    mode: DocumentEditorDrawerMode,
+    id: string | null = null,
+    copyDraftToken: string | null = null,
+  ) {
+    drawerMode.value = mode;
+    drawerId.value = mode === 'edit' ? id : null;
+    drawerCopyDraftToken.value = mode === 'new' ? copyDraftToken : null;
+  }
+
+  async function clearDrawerQueryIfPresent() {
+    if (
+      args.route.query.panel == null
+      && args.route.query.id == null
+      && args.route.query.copyDraft == null
+    ) {
+      return;
+    }
+
+    await replaceCleanRouteQuery(args.route, args.router, {
+      panel: undefined,
+      id: undefined,
+      copyDraft: undefined,
+    });
+  }
+
+  function openCreateDrawer(copyDraftToken: string | null = null) {
+    setDrawerState('new', null, copyDraftToken);
+  }
+
+  function openEditDrawer(id: string) {
+    const normalizedId = normalizeSingleQueryValue(id);
+    if (!normalizedId) return;
+    setDrawerState('edit', normalizedId);
+  }
+
+  function reopenCreatedDocument(id: string) {
+    openEditDrawer(id);
+  }
+
+  async function closeDrawer() {
+    setDrawerState('closed');
+    await clearDrawerQueryIfPresent();
+  }
+
+  function resetDrawerState() {
+    setDrawerState('closed');
+  }
+
+  watch(
+    () => [args.route.query.panel, args.route.query.id, args.route.query.copyDraft, args.documentType.value] as const,
+    ([panel, id, copyDraft]) => {
+      const normalizedPanel = normalizeSingleQueryValue(panel).toLowerCase();
+      const normalizedId = normalizeSingleQueryValue(id);
+      const copyDraftToken = normalizeSingleQueryValue(copyDraft) || null;
+
+      if (normalizedPanel === 'new') {
+        openCreateDrawer(copyDraftToken);
+        void clearDrawerQueryIfPresent();
+        return;
+      }
+
+      if (normalizedPanel === 'edit' && normalizedId) {
+        openEditDrawer(normalizedId);
+        void clearDrawerQueryIfPresent();
+      }
+    },
+    { immediate: true },
+  );
+
+  watch(
+    () => args.documentType.value,
+    () => {
+      if (
+        args.route.query.panel != null
+        || args.route.query.id != null
+        || args.route.query.copyDraft != null
+      ) {
+        return;
+      }
+
+      resetDrawerState();
+    },
+  );
+
+  return {
+    drawerMode,
+    isPanelOpen,
+    currentEditorId,
+    initialCopyDraft,
+    initialFields,
+    initialParts,
+    expandTo,
+    openCreateDrawer,
+    openEditDrawer,
+    reopenCreatedDocument,
+    closeDrawer,
+    resetDrawerState,
+    clearDrawerQueryIfPresent,
+  };
+}

package/src/ngb/editor/useEditorDrawerState.ts

@@ -0,0 +1,88 @@
+import { ref } from 'vue';
+
+import type { EntityEditorFlags } from './types';
+
+function createDefaultFlags(): EntityEditorFlags {
+  return {
+    canSave: false,
+    isDirty: false,
+    loading: false,
+    saving: false,
+    canExpand: false,
+    canDelete: false,
+    canMarkForDeletion: false,
+    canUnmarkForDeletion: false,
+    canPost: false,
+    canUnpost: false,
+    canShowAudit: false,
+    canShareLink: false,
+    extras: undefined,
+  };
+}
+
+export function useEditorDrawerState() {
+  const drawerTitle = ref('');
+  const drawerSubtitle = ref<string | undefined>(undefined);
+  const editorFlags = ref<EntityEditorFlags>(createDefaultFlags());
+  const discardOpen = ref(false);
+  let discardPromise: Promise<boolean> | null = null;
+  let discardResolve: ((value: boolean) => void) | null = null;
+
+  function resetDrawerHeading() {
+    drawerTitle.value = '';
+    drawerSubtitle.value = undefined;
+  }
+
+  function handleEditorFlags(next: EntityEditorFlags) {
+    editorFlags.value = next;
+  }
+
+  function handleEditorState(next: { title: string; subtitle?: string }) {
+    drawerTitle.value = next.title;
+    drawerSubtitle.value = next.subtitle;
+  }
+
+  function requestDiscard(): Promise<boolean> {
+    if (discardOpen.value && discardPromise) return discardPromise;
+
+    discardOpen.value = true;
+    discardPromise = new Promise<boolean>((resolve) => {
+      discardResolve = resolve;
+    });
+    return discardPromise;
+  }
+
+  function discardConfirm() {
+    discardOpen.value = false;
+    discardResolve?.(true);
+    discardResolve = null;
+    discardPromise = null;
+  }
+
+  function discardCancel() {
+    discardOpen.value = false;
+    discardResolve?.(false);
+    discardResolve = null;
+    discardPromise = null;
+  }
+
+  async function beforeCloseDrawer(): Promise<boolean> {
+    if (discardOpen.value) return false;
+    if (!editorFlags.value.isDirty) return true;
+    return await requestDiscard();
+  }
+
+  return {
+    drawerTitle,
+    drawerSubtitle,
+    editorFlags,
+    discardOpen,
+    handleEditorFlags,
+    handleEditorState,
+    resetDrawerHeading,
+    requestDiscard,
+    discardConfirm,
+    discardCancel,
+    beforeCloseDrawer,
+  };
+}