@masterteam/client-components 0.0.89 → 0.0.90

package/fesm2022/masterteam-client-components-client-list.mjs

@@ -8,7 +8,7 @@ import { Button } from '@masterteam/components/button';
 import { RuntimeActionRunner, resolveActionLabel } from '@masterteam/components/runtime-action';
 import { HttpClient } from '@angular/common/http';
 import { switchMap, map, of, Observable, share, take } from 'rxjs';
-import { resolveLocalizedLabel, serializeEntityRawValue, isSectionKey, EntitiesPreview } from '@masterteam/components/entities';
+import { resolveLocalizedLabel, serializeEntityRawValue, isSectionKey, buildDisplayEntities, EntitiesPreview } from '@masterteam/components/entities';
 import { Table, TableExportService, TableGroupingController, TableValueResolver, TableCaption } from '@masterteam/components/table';
 import * as i2 from 'primeng/skeleton';
 import { SkeletonModule } from 'primeng/skeleton';
@@ -24,6 +24,13 @@ import { PopoverModule } from 'primeng/popover';
 import { DashboardViewer } from '@masterteam/dashboard-builder';
 
 const CLIENT_LIST_RECORD_STATE_KEY = '__clientListRecordState';
+/**
+ * Row key carrying the owning record of a hierarchy row. Sits beside the row's
+ * cells rather than in a column so it travels with the row through
+ * `transformResult`, row actions and click handlers without ever rendering.
+ * Read it with {@link readClientListRowSource}.
+ */
+const CLIENT_LIST_RECORD_SOURCE_KEY = '__clientListRecordSource';
 /** Record state every list request asks for. */
 const CLIENT_LIST_DEFAULT_INCLUDE_STATE = ['escalation'];
 /**
@@ -43,7 +50,7 @@ class ClientListApiService {
      * the request carried, because a write that wants its record projected the
      * same way has to repeat them and cannot recover them from the response.
      */
-    getRows(contextKey, query, filters = []) {
+    getRows(contextKey, query, filters = [], hierarchy) {
         return this.resolveTablePropertyKeys(contextKey, query).pipe(switchMap((resolvedKeys) => {
             const propertyKeys = resolvedKeys?.length ? resolvedKeys : undefined;
             return this.queryRuntime({
@@ -55,6 +62,7 @@ class ClientListApiService {
                 filters,
                 page: this.toPage(query.skip, query.take),
                 pageSize: query.take,
+                ...(hierarchy ? { hierarchy: this.toHierarchyScope(hierarchy) } : {}),
             }).pipe(map((response) => ({ response, propertyKeys })));
         }));
     }
@@ -63,6 +71,12 @@ class ClientListApiService {
      * taken when a write reports `recordProjectionStatus: 'Unavailable'`. The
      * write itself already succeeded; this only reads, and must never be served
      * by re-submitting.
+     *
+     * `contextKey` is the context that *owns* the record, which in a hierarchy
+     * table is the row's `source.contextKey` rather than the list's own. The
+     * read deliberately carries no `hierarchy` scope: the row is filtered by its
+     * own id in its own context, which is both cheaper and immune to the record
+     * having moved out of the root's subtree since it was written.
      */
     getRecord(contextKey, request, filters) {
         return this.queryRuntime({
@@ -123,6 +137,21 @@ class ClientListApiService {
         }
         return Math.floor(skip / take) + 1;
     }
+    /**
+     * Sends the scope with both optional fields resolved rather than omitted.
+     * The backend's defaults match these, but `depth` is range-checked against
+     * `>= -1` and anything else fails the whole request — so a host that means
+     * "everything" gets `-1` written down instead of relying on an absent field
+     * surviving serialization.
+     */
+    toHierarchyScope(scope) {
+        const depth = Math.trunc(scope.depth ?? -1);
+        return {
+            rootId: scope.rootId,
+            depth: depth < -1 ? -1 : depth,
+            includeRoot: scope.includeRoot ?? false,
+        };
+    }
     toEffectiveColumnKeys(columns) {
         const keys = (columns ?? [])
             .filter((column) => typeof column === 'string' ? true : column.visible !== false)
@@ -251,6 +280,10 @@ class ClientListStateService {
             const row = {
                 Id: record.id,
                 [CLIENT_LIST_RECORD_STATE_KEY]: record.state ?? null,
+                // Only present on a hierarchy response, where rows come from several
+                // owners at once and the list's own context no longer identifies the
+                // record a row belongs to.
+                [CLIENT_LIST_RECORD_SOURCE_KEY]: record.source ?? null,
             };
             columns.forEach((column) => {
                 const property = this.resolvePropertyMeta(column.key, propertyMaps);
@@ -277,6 +310,12 @@ class ClientListStateService {
                 columns: shaped.columns,
                 rows: shaped.rows,
                 cards: [],
+                // Pre-pagination aggregates, kept verbatim off the response. They
+                // describe every matching row, so they must never be recomputed from
+                // the page — and they are absent on an ordinary list, which is a
+                // different thing from being zero.
+                totals: response.projectionMeta?.totals,
+                sourceGroups: response.projectionMeta?.sourceGroups,
                 skip,
                 take,
                 totalCount,
@@ -370,14 +409,22 @@ class ClientListStateService {
         const raw = target.rawData;
         if (!raw)
             return false;
+        // A hierarchy table cannot be patched in place. Its totals and per-owner
+        // subtotals are summed by the backend over every matching row across all
+        // pages, so a written row changes numbers this client cannot recompute —
+        // splicing the row would leave the table showing a total that no longer
+        // matches its own rows. Refuse, and let the caller reload.
+        if (config.hierarchy)
+            return false;
         return target.areaType === 'cards'
             ? this.upsertCardRecord(key, target, raw, record)
             : this.upsertRowRecord(key, target, raw, record, config);
     }
     /**
      * Drops a record the backend has deleted, without re-fetching. Returns
-     * `false` when the record is not in the loaded set, so the caller can decide
-     * whether a reload is warranted.
+     * `false` when the record is not in the loaded set — or when the list is a
+     * hierarchy table, whose server-summed totals a local removal would
+     * invalidate — so the caller can decide whether a reload is warranted.
      */
     removeRecord(key, recordId, config) {
         const target = this.itemsByKey()[key];
@@ -386,6 +433,8 @@ class ClientListStateService {
         const raw = target.rawData;
         if (!raw)
             return false;
+        if (config.hierarchy)
+            return false;
         const records = (raw.records ?? []).filter((item) => item.id !== recordId);
         if (target.areaType === 'cards') {
             const cards = target.cards.filter((card) => card.id !== recordId);
@@ -1495,17 +1544,25 @@ class ClientListCardsView {
     badgeLegend = computed(() => {
         const entries = new Map();
         for (const card of this.visibleCards()) {
-            for (const entity of card.entities ?? []) {
+            // A card's entities are unexpanded: a LeafDetails one still carries the
+            // fetch payload (`childSchemas`), not the per-level value the badges are
+            // painted from. Expanding it here — the same split `mt-entities-preview`
+            // does to render the card — is what makes the legend list exactly the
+            // badges on screen, statuses and phases alike.
+            for (const entity of buildDisplayEntities(card.entities ?? [])) {
                 if (entity.viewType !== 'LeafDetails')
                     continue;
                 const value = entity.value;
-                for (const status of value?.statuses ?? []) {
-                    if (!status?.key || entries.has(status.key))
+                const badges = value?.kind === 'phase'
+                    ? (value.phases ?? [])
+                    : (value?.statuses ?? []);
+                for (const badge of badges) {
+                    if (!badge?.key || entries.has(badge.key))
                         continue;
-                    const color = status.color ?? DEFAULT_BADGE_COLOR;
-                    entries.set(status.key, {
-                        key: status.key,
-                        label: status.display || status.key,
+                    const color = badge.color ?? DEFAULT_BADGE_COLOR;
+                    entries.set(badge.key, {
+                        key: badge.key,
+                        label: badge.display || badge.key,
                         color,
                         textColor: readableTextOn(color),
                     });
@@ -1978,6 +2035,54 @@ function serializeFilters(filters) {
     return JSON.stringify(filters ?? []);
 }
 
+/**
+ * Reads the owning record off a hierarchy row. Returns null for a row from an
+ * ordinary list, which has no owner other than the list's own context.
+ *
+ * Use this before addressing anything at a row — an edit, a navigation, a
+ * permission check. The list's configured `contextKey` is the aggregation
+ * scope in a hierarchy table, not the row's home.
+ */
+function readClientListRowSource(row) {
+    const source = row?.[CLIENT_LIST_RECORD_SOURCE_KEY];
+    return isRecordSource(source) ? source : null;
+}
+/**
+ * Looks a total up by property key.
+ *
+ * Always go through this rather than indexing `totals`. The backend fills the
+ * array from the module's configured summary keys — one `amount` entry on the
+ * financial module, nothing at all on every other module — so the array being
+ * present does not mean the key you want is in it, and position means nothing.
+ */
+function findClientListTotal(totals, propertyKey) {
+    const wanted = propertyKey.trim().toLowerCase();
+    return ((totals ?? []).find((total) => (total.propertyKey ?? '').trim().toLowerCase() === wanted) ?? null);
+}
+/**
+ * Whether a total left rows out — some row's value was missing or not a
+ * number, so the sum is over fewer rows than the table reports.
+ *
+ * A total in this state must be presented as incomplete. Rendering it as a
+ * plain figure states a portfolio total the data does not support.
+ */
+function isClientListTotalIncomplete(total) {
+    return (total?.missingValueCount ?? 0) > 0;
+}
+/**
+ * The subtotal group for one owning record, by its level-data id.
+ */
+function findClientListSourceGroup(groups, levelDataId) {
+    return ((groups ?? []).find((group) => group.source?.levelDataId === levelDataId) ??
+        null);
+}
+function isRecordSource(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.levelDataId === 'number' &&
+        typeof value.contextKey === 'string');
+}
+
 const DEFAULT_AREA_TYPE = 'table';
 const DEFAULT_MODE = 'auto';
 const DEFAULT_TYPE = 'form';
@@ -2138,6 +2243,15 @@ class ClientList {
             return;
         if (this.isPendingApprovalWrite(result))
             return;
+        // A hierarchy table has no in-place path: its totals and per-owner
+        // subtotals are summed server-side over every matching row, and the
+        // written record lives in a descendant context this list's own id filter
+        // would not even match. Reload outright rather than spend a read on a
+        // record that cannot be spliced anyway.
+        if (item.config.hierarchy) {
+            this.reloadByKey(itemKey);
+            return;
+        }
         const recordId = this.toFiniteNumber(result?.recordId);
         const record = this.toWriteRecord(result, recordId);
         if (record) {
@@ -2510,10 +2624,17 @@ class ClientList {
         const recordId = this.resolveRecordId(config, row);
         if (recordId == null)
             return null;
+        // A hierarchy row belongs to a descendant, not to the list's own context.
+        // Its actions, its permissions and the instance they apply to are all the
+        // owner's — asking the aggregation context for them would read the wrong
+        // record's actions, or none at all.
+        const source = readClientListRowSource(row);
         return {
             listKey: item.key,
-            contextKey: item.config.contextKey ?? null,
-            instanceId: item.config.instanceId ?? null,
+            contextKey: source?.contextKey ?? item.config.contextKey ?? null,
+            listContextKey: item.config.contextKey ?? null,
+            source,
+            instanceId: source?.levelDataId ?? item.config.instanceId ?? null,
             moduleId: item.config.moduleId ?? 0,
             row,
             recordId,
@@ -2689,7 +2810,9 @@ class ClientList {
         this.inFlightRequestSignatures.set(key, requestSignature);
         this.state.setLoading(key, true);
         this.state.setError(key, null);
-        const sub = this.api.getRows(config.contextKey, query, filters).subscribe({
+        const sub = this.api
+            .getRows(config.contextKey, query, filters, config.hierarchy)
+            .subscribe({
             next: ({ response, propertyKeys }) => {
                 let hasLoadedData = false;
                 if (response.data) {
@@ -2840,6 +2963,20 @@ class ClientList {
             return DEFAULT_MODE;
         return (columnKeys ?? []).length > 0 ? 'override' : DEFAULT_MODE;
     }
+    /**
+     * Descendant scope only survives where the backend accepts it: a table, with
+     * a usable root id. Anywhere else it is dropped rather than sent, because
+     * the backend answers an unsupported combination with a 400 that takes the
+     * whole list down — a cards area that happens to share a config object would
+     * otherwise render nothing at all.
+     */
+    resolveHierarchyScope(config, areaType) {
+        const scope = config?.hierarchy;
+        if (!scope || areaType !== 'table')
+            return null;
+        const rootId = this.resolvePositiveInteger(scope.rootId);
+        return rootId == null ? null : { ...scope, rootId };
+    }
     toNormalizedConfig(config, type, areaType, mode, isPaginated, take, showHeader, collapseEnabled, layout) {
         const informativeConfig = this.asInformativeConfig(config);
         const formConfig = this.asFormConfig(config);
@@ -2847,6 +2984,7 @@ class ClientList {
             contextKey: formConfig?.contextKey ?? null,
             instanceId: formConfig?.instanceId ?? informativeConfig?.instanceId ?? null,
             filters: formConfig?.filters ?? informativeConfig?.filters ?? [],
+            hierarchy: this.resolveHierarchyScope(formConfig, areaType),
             levelId: informativeConfig?.levelId ?? null,
             moduleId: informativeConfig?.moduleId ?? 0,
             type,
@@ -3023,6 +3161,10 @@ class ClientList {
             config.areaType,
             config.contextKey ?? 'x',
             this.serializeFilters(filters),
+            // Two lists on the same context and filters are still different fetches
+            // when they are rooted at different records — without this the second
+            // one would be served the first one's rows from the in-flight cache.
+            this.serializeHierarchy(config.hierarchy),
             query.mode,
             query.skip,
             query.take,
@@ -3077,6 +3219,15 @@ class ClientList {
     serializeFilters(filters) {
         return JSON.stringify(filters ?? []);
     }
+    serializeHierarchy(hierarchy) {
+        if (!hierarchy)
+            return 'x';
+        return [
+            hierarchy.rootId,
+            hierarchy.depth ?? -1,
+            hierarchy.includeRoot ?? false,
+        ].join(',');
+    }
     resolveFetchFilters(key, config) {
         return mergeRuntimeFilters(config.filters, this.runtimeFilters.get(key), this.state.itemsByKey()[key]?.columns);
     }
@@ -3106,5 +3257,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { CLIENT_LIST_DEFAULT_INCLUDE_STATE, CLIENT_LIST_RECORD_ID_FILTER_KEY, CLIENT_LIST_RECORD_STATE_KEY, ClientList, ClientListApiService, ClientListRuntimeActionsService, ClientListStateService, ClientListToolbarService, defaultResolveRecordId };
+export { CLIENT_LIST_DEFAULT_INCLUDE_STATE, CLIENT_LIST_RECORD_ID_FILTER_KEY, CLIENT_LIST_RECORD_SOURCE_KEY, CLIENT_LIST_RECORD_STATE_KEY, ClientList, ClientListApiService, ClientListRuntimeActionsService, ClientListStateService, ClientListToolbarService, defaultResolveRecordId, findClientListSourceGroup, findClientListTotal, isClientListTotalIncomplete, readClientListRowSource };
 //# sourceMappingURL=masterteam-client-components-client-list.mjs.map