@ngbplatform/ui 1.3.0

package/src/ngb/metadata/types.ts

@@ -0,0 +1,276 @@
+import type { RouteLocationRaw } from 'vue-router'
+
+export type Awaitable<T> = T | Promise<T>
+
+export type DataType = string
+export type UiControl = number
+export type ColumnAlign = number
+export type EntityKind = number
+export type DocumentStatusValue = number
+export type ActionKind = number
+
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[]
+export type JsonObject = { [key: string]: JsonValue }
+export type RecordFields = Record<string, JsonValue>
+export type RecordPartRow = RecordFields
+export type RecordPart = { rows: RecordPartRow[] }
+export type RecordParts = Record<string, RecordPart>
+export type RecordPayload = {
+  fields?: RecordFields | null
+  parts?: RecordParts | null
+}
+
+export type LookupSource =
+  | {
+      kind: 'catalog'
+      catalogType: string
+      displayTemplate?: string | null
+    }
+  | {
+      kind: 'document'
+      documentTypes: string[]
+    }
+  | {
+      kind: 'coa'
+    }
+
+export type LookupHint =
+  | {
+      kind: 'catalog'
+      catalogType: string
+      filters?: Record<string, string>
+    }
+  | {
+      kind: 'document'
+      documentTypes: string[]
+    }
+  | {
+      kind: 'coa'
+    }
+
+export type LookupItem = {
+  id: string
+  label: string
+  meta?: string
+}
+
+export type FieldOption = {
+  value: string
+  label: string
+}
+
+export type ColumnMetadata = {
+  key: string
+  label: string
+  dataType: DataType
+  isSortable: boolean
+  widthPx?: number | null
+  align: ColumnAlign
+  lookup?: LookupSource | null
+  options?: FieldOption[] | null
+}
+
+export type ListFilterOption = FieldOption
+
+export type ListFilterField = {
+  key: string
+  label: string
+  dataType: DataType
+  isMulti?: boolean
+  lookup?: LookupSource | null
+  options?: ListFilterOption[] | null
+  description?: string | null
+  supportsIncludeDescendants?: boolean
+}
+
+export type ListMetadata = {
+  columns: ColumnMetadata[]
+  filters?: ListFilterField[] | null
+}
+
+export type FieldValidation = {
+  maxLength?: number | null
+  min?: number | null
+  max?: number | null
+  regex?: string | null
+}
+
+export type FieldMetadata = {
+  key: string
+  label: string
+  dataType: DataType
+  uiControl: UiControl
+  isRequired: boolean
+  isReadOnly: boolean
+  readOnlyWhenStatusIn?: DocumentStatusValue[] | null
+  lookup?: LookupSource | null
+  validation?: FieldValidation | null
+  options?: FieldOption[] | null
+  helpText?: string | null
+}
+
+export type FormRow = {
+  fields: FieldMetadata[]
+}
+
+export type FormSection = {
+  title: string
+  rows: FormRow[]
+}
+
+export type FormMetadata = {
+  sections: FormSection[]
+}
+
+export type PartMetadata = {
+  partCode: string
+  title: string
+  list: ListMetadata
+  allowAddRemoveRows?: boolean
+  readOnlyWhenPosted?: boolean
+}
+
+export type ActionMetadata = {
+  code: string
+  label: string
+  kind?: ActionKind
+  requiresConfirm?: boolean
+  visibleWhenStatusIn?: DocumentStatusValue[] | null
+}
+
+export type CatalogTypeMetadata = {
+  catalogType: string
+  displayName: string
+  kind: EntityKind
+  icon?: string | null
+  list?: ListMetadata | null
+  form?: FormMetadata | null
+  parts?: PartMetadata[] | null
+  capabilities?: CatalogCapabilities | null
+}
+
+export type CatalogCapabilities = {
+  canCreate?: boolean
+  canEdit?: boolean
+  canDelete?: boolean
+  canMarkForDeletion?: boolean
+}
+
+export type DocumentCapabilities = {
+  canCreate?: boolean
+  canEditDraft?: boolean
+  canDeleteDraft?: boolean
+  canPost?: boolean
+  canUnpost?: boolean
+  canRepost?: boolean
+  canMarkForDeletion?: boolean
+  supportsActions?: boolean
+  canViewEffects?: boolean
+  canViewFlow?: boolean
+}
+
+export type DocumentPresentation = {
+  displayName?: string | null
+  hasNumber?: boolean
+  computedDisplay?: boolean
+  hideSystemFieldsInEditor?: boolean
+}
+
+export type DocumentTypeMetadata = {
+  documentType: string
+  displayName: string
+  kind: EntityKind
+  icon?: string | null
+  list?: ListMetadata | null
+  form?: FormMetadata | null
+  parts?: PartMetadata[] | null
+  actions?: ActionMetadata[] | null
+  presentation?: DocumentPresentation | null
+  capabilities?: DocumentCapabilities | null
+}
+
+export type EntityFormModel = Record<string, unknown>
+
+export type ReferenceValue = {
+  id: string
+  display: string
+}
+
+export type FilterLookupItem = LookupItem
+
+export type FilterFieldState<TItem extends FilterLookupItem = FilterLookupItem> = {
+  raw: string
+  items: TItem[]
+  includeDescendants?: boolean
+}
+
+export type FilterFieldOption = {
+  value: unknown
+  label: string
+}
+
+export type FilterFieldLike = {
+  label: string
+  dataType?: unknown
+  isMulti?: boolean
+  lookup?: LookupSource | null
+  options?: readonly FilterFieldOption[] | null
+  supportsIncludeDescendants?: boolean
+}
+
+export type LookupStoreApi<TItem extends LookupItem = LookupItem> = {
+  searchCatalog: (
+    catalogType: string,
+    query: string,
+    options?: { filters?: Record<string, string> },
+  ) => Promise<TItem[]>
+  searchCoa: (query: string) => Promise<TItem[]>
+  searchDocuments: (documentTypes: string[], query: string) => Promise<TItem[]>
+  ensureCatalogLabels: (catalogType: string, ids: string[]) => Promise<void>
+  ensureCoaLabels: (ids: string[]) => Promise<void>
+  ensureAnyDocumentLabels: (documentTypes: string[], ids: string[]) => Promise<void>
+  labelForCatalog: (catalogType: string, id: unknown) => string
+  labelForCoa: (id: unknown) => string
+  labelForAnyDocument: (documentTypes: string[], id: unknown) => string
+}
+
+export type ResolvedLookupSource = LookupHint | LookupSource
+
+export type FieldResolverArgs = {
+  entityTypeCode: string
+  model: EntityFormModel
+  field: FieldMetadata
+}
+
+export type FieldReadonlyArgs = FieldResolverArgs & {
+  status?: DocumentStatusValue
+  forceReadonly?: boolean
+}
+
+export type FieldHiddenArgs = FieldResolverArgs & {
+  isDocumentEntity: boolean
+}
+
+export type LookupHintArgs = FieldResolverArgs
+
+export type LookupSearchArgs = {
+  hint: LookupHint
+  query: string
+}
+
+export type LookupTargetArgs = {
+  hint: LookupHint
+  value: unknown
+  routeFullPath: string
+}
+
+export type MetadataFormBehavior = {
+  resolveFieldOptions?: (args: FieldResolverArgs) => FieldOption[] | null
+  resolveLookupHint?: (args: LookupHintArgs) => LookupHint | null
+  isFieldReadonly?: (args: FieldReadonlyArgs) => boolean
+  isFieldHidden?: (args: FieldHiddenArgs) => boolean
+  findDisplayField?: (form: FormMetadata) => FieldMetadata | null
+  searchLookup?: (args: LookupSearchArgs) => Awaitable<LookupItem[]>
+  buildLookupTargetUrl?: (args: LookupTargetArgs) => Awaitable<RouteLocationRaw | null>
+}

package/src/ngb/metadata/useMetadataListFilters.ts

@@ -0,0 +1,306 @@
+import { computed, onBeforeUnmount, ref, watch, type ComputedRef } from 'vue';
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router';
+
+import { isGuidString } from '../utils/guid';
+import { stableStringify } from '../utils/stableValue';
+import { normalizeSingleQueryValue, setCleanRouteQuery } from '../router/queryParams';
+import {
+  buildFilterOptionLabelsByKey,
+  hydrateResolvedLookupItems,
+  joinFilterValues,
+  labelForResolvedLookup,
+  optionLabelForFilter,
+  searchResolvedLookupItems,
+  splitFilterValues,
+  summarizeFilterValues,
+} from './filtering';
+import type {
+  FilterFieldState,
+  LookupHint,
+  LookupItem,
+  LookupStoreApi,
+  ListFilterField,
+} from './types';
+
+export type MetadataListFilterBadge = {
+  key: string;
+  text: string;
+};
+
+export type UseMetadataListFiltersArgs<
+  TField extends ListFilterField = ListFilterField,
+  TItem extends LookupItem = LookupItem,
+> = {
+  route: RouteLocationNormalizedLoaded;
+  router: Router;
+  entityTypeCode: ComputedRef<string>;
+  filters: ComputedRef<readonly TField[]>;
+  lookupStore: LookupStoreApi<TItem>;
+  resolveLookupHint: (args: {
+    entityTypeCode: string;
+    field: TField;
+  }) => LookupHint | null;
+  commitDelayMs?: number;
+};
+
+function buildEmptyFilterState<TField extends Pick<ListFilterField, 'key'>, TItem extends LookupItem>(
+  filters: readonly TField[],
+): Record<string, FilterFieldState<TItem>> {
+  return Object.fromEntries(filters.map((field) => [field.key, { raw: '', items: [] }]));
+}
+
+export function useMetadataListFilters<
+  TField extends ListFilterField = ListFilterField,
+  TItem extends LookupItem = LookupItem,
+>(
+  args: UseMetadataListFiltersArgs<TField, TItem>,
+) {
+  const filterDraft = ref<Record<string, FilterFieldState<TItem>>>({});
+  const lookupItemsByFilterKey = ref<Record<string, TItem[]>>({});
+  const lookupSearchSeqByFilterKey = ref<Record<string, number>>({});
+  const filterDraftSyncToken = ref(0);
+  const filterCommitTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const commitDelayMs = args.commitDelayMs ?? 280;
+
+  function listFilterStateFor(key: string): FilterFieldState<TItem> {
+    return filterDraft.value[key] ?? { raw: '', items: [] };
+  }
+
+  function setListFilterState(key: string, next: FilterFieldState<TItem>) {
+    filterDraft.value = {
+      ...filterDraft.value,
+      [key]: next,
+    };
+  }
+
+  function clearPendingFilterCommit(key: string) {
+    const timer = filterCommitTimers.get(key);
+    if (!timer) return;
+    clearTimeout(timer);
+    filterCommitTimers.delete(key);
+  }
+
+  function clearAllPendingFilterCommits() {
+    for (const timer of filterCommitTimers.values()) clearTimeout(timer);
+    filterCommitTimers.clear();
+  }
+
+  function resolveListFilterLookupHint(field: TField): LookupHint | null {
+    return args.resolveLookupHint({
+      entityTypeCode: args.entityTypeCode.value,
+      field,
+    });
+  }
+
+  async function searchListFilterLookupItems(field: TField, query: string): Promise<TItem[]> {
+    const hint = resolveListFilterLookupHint(field);
+    if (!hint) return [];
+    return await searchResolvedLookupItems(args.lookupStore, hint, query);
+  }
+
+  async function syncFilterDraftFromRoute() {
+    const filters = args.filters.value;
+    const token = ++filterDraftSyncToken.value;
+    const next = buildEmptyFilterState<TField, TItem>(filters);
+
+    for (const field of filters) {
+      const raw = normalizeSingleQueryValue(args.route.query[field.key]);
+      next[field.key] = { raw, items: [] };
+    }
+
+    filterDraft.value = next;
+
+    for (const field of filters) {
+      if (!field.lookup) continue;
+
+      const raw = normalizeSingleQueryValue(args.route.query[field.key]);
+      const ids = (field.isMulti ? splitFilterValues(raw) : [raw]).filter(isGuidString);
+      if (ids.length === 0) continue;
+
+      const hint = resolveListFilterLookupHint(field);
+      next[field.key] = {
+        raw,
+        items: hint ? await hydrateResolvedLookupItems(args.lookupStore, hint, ids) : [],
+      };
+
+      if (token !== filterDraftSyncToken.value) return;
+    }
+
+    if (token === filterDraftSyncToken.value) {
+      filterDraft.value = next;
+    }
+  }
+
+  async function replaceRouteQuery(mutator: (query: Record<string, unknown>) => void) {
+    const nextQuery: Record<string, unknown> = { ...args.route.query };
+    mutator(nextQuery);
+    await setCleanRouteQuery(args.route, args.router, nextQuery, 'replace');
+  }
+
+  async function applyFilterValue(key: string, value: string) {
+    clearPendingFilterCommit(key);
+    await replaceRouteQuery((query) => {
+      query[key] = value || undefined;
+      query.offset = 0;
+    });
+  }
+
+  function scheduleFilterCommit(key: string, value: string) {
+    clearPendingFilterCommit(key);
+    const timer = setTimeout(() => {
+      filterCommitTimers.delete(key);
+      void applyFilterValue(key, value.trim());
+    }, commitDelayMs);
+    filterCommitTimers.set(key, timer);
+  }
+
+  function isImmediateFilter(field: TField): boolean {
+    return !!field.lookup || (field.options?.length ?? 0) > 0;
+  }
+
+  async function handleLookupQuery(payload: { key: string; query: string }) {
+    const field = args.filters.value.find((entry) => entry.key === payload.key);
+    if (!field?.lookup) return;
+
+    const nextSeq = (lookupSearchSeqByFilterKey.value[payload.key] ?? 0) + 1;
+    lookupSearchSeqByFilterKey.value = {
+      ...lookupSearchSeqByFilterKey.value,
+      [payload.key]: nextSeq,
+    };
+
+    const items = payload.query.trim()
+      ? await searchListFilterLookupItems(field, payload.query)
+      : [];
+
+    if ((lookupSearchSeqByFilterKey.value[payload.key] ?? 0) !== nextSeq) return;
+
+    lookupItemsByFilterKey.value = {
+      ...lookupItemsByFilterKey.value,
+      [payload.key]: items,
+    };
+  }
+
+  function handleItemsUpdate(payload: { key: string; items: TItem[] }) {
+    const raw = joinFilterValues(payload.items.map((item) => item.id));
+    setListFilterState(payload.key, {
+      raw,
+      items: payload.items.map((item) => ({ ...item })),
+    });
+
+    void applyFilterValue(payload.key, raw);
+  }
+
+  function handleValueUpdate(payload: { key: string; value: string }) {
+    const field = args.filters.value.find((entry) => entry.key === payload.key);
+    if (!field) return;
+
+    setListFilterState(payload.key, {
+      raw: payload.value,
+      items: [],
+    });
+
+    if (isImmediateFilter(field)) {
+      void applyFilterValue(payload.key, payload.value.trim());
+      return;
+    }
+
+    scheduleFilterCommit(payload.key, payload.value);
+  }
+
+  async function undo() {
+    clearAllPendingFilterCommits();
+    filterDraft.value = buildEmptyFilterState<TField, TItem>(args.filters.value);
+
+    await replaceRouteQuery((query) => {
+      for (const field of args.filters.value) delete query[field.key];
+      query.offset = 0;
+    });
+  }
+
+  const optionLabelsByColumnKey = computed(() => buildFilterOptionLabelsByKey(args.filters.value));
+
+  const activeFilterBadges = computed<MetadataListFilterBadge[]>(() =>
+    args.filters.value
+      .map((field) => {
+        const appliedRaw = normalizeSingleQueryValue(args.route.query[field.key]);
+        if (!appliedRaw) return null;
+
+        const state = listFilterStateFor(field.key);
+        const selectedLabels = state.raw.trim() === appliedRaw
+          ? new Map(
+              state.items
+                .map((item) => [
+                  String(item.id ?? '').trim().toLowerCase(),
+                  String(item.label ?? item.id ?? '').trim(),
+                ] satisfies [string, string])
+                .filter((entry) => entry[0].length > 0 && entry[1].length > 0),
+            )
+          : new Map<string, string>();
+        const lookupHint = field.lookup ? resolveListFilterLookupHint(field) : null;
+        const displayValues = (field.isMulti ? splitFilterValues(appliedRaw) : [appliedRaw])
+          .map((value) => {
+            const normalized = value.trim();
+            if (!normalized) return '';
+
+            const fromDraft = selectedLabels.get(normalized.toLowerCase());
+            if (fromDraft) return fromDraft;
+            if (lookupHint) return labelForResolvedLookup(args.lookupStore, lookupHint, normalized);
+            return optionLabelForFilter(field, normalized) || normalized;
+          })
+          .filter((value) => value.length > 0);
+        const summary = summarizeFilterValues(displayValues);
+        if (!summary) return null;
+
+        return {
+          key: field.key,
+          text: `${field.label}: ${summary}`,
+        } satisfies MetadataListFilterBadge;
+      })
+      .filter((entry): entry is MetadataListFilterBadge => !!entry),
+  );
+
+  const hasActiveFilters = computed(() => activeFilterBadges.value.length > 0);
+  const canUndoFilters = computed(() =>
+    hasActiveFilters.value
+    || Object.values(filterDraft.value).some((state) => state.items.length > 0 || state.raw.trim().length > 0),
+  );
+
+  watch(
+    () => stableStringify(
+      args.filters.value
+        .map((field) => [field.key, normalizeSingleQueryValue(args.route.query[field.key])])
+        .sort(([left], [right]) => String(left).localeCompare(String(right))),
+    ),
+    () => {
+      void syncFilterDraftFromRoute();
+    },
+    { immediate: true },
+  );
+
+  watch(
+    () => args.entityTypeCode.value,
+    () => {
+      filterDraft.value = {};
+      lookupItemsByFilterKey.value = {};
+      lookupSearchSeqByFilterKey.value = {};
+      clearAllPendingFilterCommits();
+    },
+  );
+
+  onBeforeUnmount(() => {
+    clearAllPendingFilterCommits();
+  });
+
+  return {
+    filterDraft,
+    lookupItemsByFilterKey,
+    optionLabelsByColumnKey,
+    activeFilterBadges,
+    hasActiveFilters,
+    canUndoFilters,
+    handleLookupQuery,
+    handleItemsUpdate,
+    handleValueUpdate,
+    undo,
+  };
+}