@masterteam/client-components 0.0.85 → 0.0.87

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

@@ -7,7 +7,7 @@ import { TranslocoService, TranslocoModule, TranslocoPipe } from '@jsverse/trans
 import { Button } from '@masterteam/components/button';
 import { RuntimeActionRunner, resolveActionLabel } from '@masterteam/components/runtime-action';
 import { HttpClient } from '@angular/common/http';
-import { switchMap, of, map, Observable, share, take } from 'rxjs';
+import { switchMap, map, of, Observable, share, take } from 'rxjs';
 import { resolveLocalizedLabel, serializeEntityRawValue, isSectionKey, EntitiesPreview } from '@masterteam/components/entities';
 import { Table, TableExportService, TableGroupingController, TableValueResolver, TableCaption } from '@masterteam/components/table';
 import * as i2 from 'primeng/skeleton';
@@ -23,22 +23,65 @@ import * as i3 from 'primeng/popover';
 import { PopoverModule } from 'primeng/popover';
 import { DashboardViewer } from '@masterteam/dashboard-builder';
 
-const DEFAULT_INCLUDE_STATE = ['escalation'];
+const CLIENT_LIST_RECORD_STATE_KEY = '__clientListRecordState';
+/** Record state every list request asks for. */
+const CLIENT_LIST_DEFAULT_INCLUDE_STATE = ['escalation'];
+/**
+ * `fetch/query` filter key that selects a single record by its own id. Reading
+ * one record back after a write filters on this, never on the list's scope
+ * filters alone — those match a whole page, not the row that just changed.
+ */
+const CLIENT_LIST_RECORD_ID_FILTER_KEY = 'id';
+
+const DEFAULT_INCLUDE_STATE = CLIENT_LIST_DEFAULT_INCLUDE_STATE;
 class ClientListApiService {
     http = inject(HttpClient);
     runtimeFetchBaseUrl = 'fetch/query';
     informativeBaseUrl = 'LevelData';
+    /**
+     * Fetches a table page. Resolves to the response **and** the `propertyKeys`
+     * 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 = []) {
-        return this.resolveTablePropertyKeys(contextKey, query).pipe(switchMap((propertyKeys) => this.queryRuntime({
+        return this.resolveTablePropertyKeys(contextKey, query).pipe(switchMap((resolvedKeys) => {
+            const propertyKeys = resolvedKeys?.length ? resolvedKeys : undefined;
+            return this.queryRuntime({
+                contextKey,
+                projection: 'Table',
+                surfaceKey: 'table',
+                includeState: [...DEFAULT_INCLUDE_STATE],
+                propertyKeys,
+                filters,
+                page: this.toPage(query.skip, query.take),
+                pageSize: query.take,
+            }).pipe(map((response) => ({ response, propertyKeys })));
+        }));
+    }
+    /**
+     * Reads a single record back with the list's own query settings — the path
+     * taken when a write reports `recordProjectionStatus: 'Unavailable'`. The
+     * write itself already succeeded; this only reads, and must never be served
+     * by re-submitting.
+     */
+    getRecord(contextKey, request, filters) {
+        return this.queryRuntime({
             contextKey,
-            projection: 'Table',
-            surfaceKey: 'table',
-            includeState: [...DEFAULT_INCLUDE_STATE],
-            propertyKeys: propertyKeys?.length ? propertyKeys : undefined,
+            projection: request.projection,
+            surfaceKey: request.surfaceKey,
+            includeState: request.includeState
+                ? [...request.includeState]
+                : [...DEFAULT_INCLUDE_STATE],
+            propertyKeys: request.propertyKeys?.length
+                ? request.propertyKeys
+                : undefined,
             filters,
-            page: this.toPage(query.skip, query.take),
-            pageSize: query.take,
-        })));
+            page: 1,
+            pageSize: 1,
+            ...(request.projection === 'Card'
+                ? { display: { areas: ['card'] } }
+                : {}),
+        });
     }
     getCards(contextKey, filters = [], skip, take) {
         // `page` and `pageSize` must be sent together or not at all (fetch/query
@@ -108,8 +151,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 
-const CLIENT_LIST_RECORD_STATE_KEY = '__clientListRecordState';
-
 const UNSORTABLE_ENTITY_VIEW_TYPES = new Set([
     'Attachment',
     'Checkbox',
@@ -306,6 +347,146 @@ class ClientListStateService {
             },
         });
     }
+    /**
+     * Splices a canonical record into the data the list already holds, so a
+     * create or update lands without re-fetching the page.
+     *
+     * Tables replay the whole page through {@link setRowsResult}: for a table
+     * the rendered page *is* the raw response, so replaying it keeps the catalog
+     * lookup, the column build and the host `transformResult` hook on exactly
+     * one code path — a second mapper for single rows would drift from the one
+     * that built the rest of the table. Cards cannot replay: with infinite
+     * scroll `rawData` holds only the last page while `cards` holds every page,
+     * so a single card is built and merged into the accumulated set instead.
+     *
+     * Returns `false` when there is nothing to splice into — an informative
+     * dashboard, or a list that never completed a load. The caller then falls
+     * back to a real fetch rather than inventing state.
+     */
+    upsertRecord(key, record, config) {
+        const target = this.itemsByKey()[key];
+        if (!target || target.type !== 'form')
+            return false;
+        const raw = target.rawData;
+        if (!raw)
+            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.
+     */
+    removeRecord(key, recordId, config) {
+        const target = this.itemsByKey()[key];
+        if (!target || target.type !== 'form')
+            return false;
+        const raw = target.rawData;
+        if (!raw)
+            return false;
+        const records = (raw.records ?? []).filter((item) => item.id !== recordId);
+        if (target.areaType === 'cards') {
+            const cards = target.cards.filter((card) => card.id !== recordId);
+            if (cards.length === target.cards.length)
+                return false;
+            this.patchItem(key, {
+                ...target,
+                cards,
+                totalCount: Math.max(0, target.totalCount - 1),
+                error: null,
+                rawData: this.withRecords(raw, records, -1),
+            });
+            return true;
+        }
+        if (records.length === (raw.records ?? []).length)
+            return false;
+        this.setRowsResult(key, this.withRecords(raw, records, -1), config, target.skip, target.take);
+        return true;
+    }
+    upsertRowRecord(key, target, raw, record, config) {
+        // No columns means no completed table load to splice into.
+        if (!target.columns.length)
+            return false;
+        const records = [...(raw.records ?? [])];
+        const index = records.findIndex((item) => item.id === record.id);
+        if (index >= 0) {
+            records[index] = this.mergeRecord(records[index], record);
+        }
+        else {
+            // The backend owns the real ordering and does not say where the new
+            // record landed, so it goes to the top of the page in view: the user
+            // has to see what they just created. The next real load puts it in its
+            // true place.
+            records.unshift(record);
+            // Keep the page the size the paginator promises — the row pushed off
+            // the end now lives on the next page.
+            if (config.isPaginated &&
+                target.take > 0 &&
+                records.length > target.take) {
+                records.length = target.take;
+            }
+        }
+        this.setRowsResult(key, this.withRecords(raw, records, index >= 0 ? 0 : 1), config, target.skip, target.take);
+        return true;
+    }
+    upsertCardRecord(key, target, raw, record) {
+        if (!raw.projectionMeta)
+            return false;
+        const previous = (raw.records ?? []).find((item) => item.id === record.id);
+        const merged = previous ? this.mergeRecord(previous, record) : record;
+        const [card] = this.toCards({ ...raw, records: [merged] });
+        if (!card)
+            return false;
+        const index = target.cards.findIndex((item) => item.id === card.id);
+        const isInsert = index < 0;
+        const cards = isInsert
+            ? [card, ...target.cards]
+            : target.cards.map((item, position) => position === index ? card : item);
+        const records = [...(raw.records ?? [])];
+        const recordIndex = records.findIndex((item) => item.id === merged.id);
+        if (recordIndex >= 0)
+            records[recordIndex] = merged;
+        else
+            records.unshift(merged);
+        this.patchItem(key, {
+            ...target,
+            cards,
+            totalCount: isInsert ? target.totalCount + 1 : target.totalCount,
+            error: null,
+            rawData: this.withRecords(raw, records, isInsert ? 1 : 0),
+        });
+        return true;
+    }
+    /**
+     * Overlays the written record on the one being replaced, key by key. A
+     * cleared property comes back explicitly (`{ raw: null, value: null }`) and
+     * overwrites; only a key the backend left out entirely keeps its previous
+     * cell, which beats blanking a value that did not actually change.
+     */
+    mergeRecord(previous, next) {
+        return {
+            ...previous,
+            ...next,
+            values: { ...previous.values, ...next.values },
+        };
+    }
+    withRecords(raw, records, totalCountDelta) {
+        return {
+            ...raw,
+            records,
+            pagination: raw.pagination
+                ? {
+                    ...raw.pagination,
+                    totalCount: Math.max(0, raw.pagination.totalCount + totalCountDelta),
+                }
+                : raw.pagination,
+        };
+    }
+    patchItem(key, next) {
+        this.itemsByKey.set({ ...this.itemsByKey(), [key]: next });
+    }
     /**
      * Appends `next` to `current`, dropping any card whose id is already
      * present. Ids are the grid's `@for` track key, so duplicates are a runtime
@@ -378,8 +559,6 @@ class ClientListStateService {
             existing.areaType !== item.areaType) {
             return item;
         }
-        const keepPaging = existing.config.isPaginated === item.config.isPaginated &&
-            existing.take === item.take;
         return {
             ...item,
             loading: existing.loading,
@@ -390,7 +569,12 @@ class ClientListStateService {
             columns: existing.columns,
             rows: existing.rows,
             cards: existing.cards,
-            skip: keepPaging ? existing.skip : item.skip,
+            // Paging is settled by the caller, which compared the incoming config
+            // against the previous one. Re-deciding it here — with only the two
+            // states and no view of what changed in the config — is what used to
+            // drop the user's page whenever their rows-per-page differed from the
+            // configured default.
+            skip: item.skip,
             take: item.take,
             expanded: existing.expanded,
             dashboardData: existing.dashboardData,
@@ -1760,6 +1944,40 @@ function toScalar(value) {
         item['displayName']);
 }
 
+/**
+ * Whether the offset a list is currently sitting on still describes the same
+ * result set, i.e. this reconfigure changed nothing about what gets fetched.
+ *
+ * Hosts rebuild the `configurations` array from a `computed()`, so *any*
+ * unrelated state change — a permission refresh after a write, a language
+ * switch, a re-rendered header template — hands the list a brand new array
+ * with identical content. That must not move the user off their page, and
+ * must not cost a request.
+ *
+ * The page size is compared **as configured**, never as currently applied. The
+ * table owns its rows-per-page: the user picks it from the paginator and
+ * `mt-table` restores a persisted value, and either of those legitimately
+ * leaves the runtime `take` different from the configured one. Reading that
+ * difference as drift to correct is what used to reset the paginator and
+ * refetch page 1 on every reconfigure.
+ */
+function preservesPaging(existing, areaType, next) {
+    if (!existing ||
+        existing.type !== 'form' ||
+        existing.areaType !== areaType ||
+        next.type !== 'form') {
+        return false;
+    }
+    const current = existing.config;
+    return (current.isPaginated === next.isPaginated &&
+        current.take === next.take &&
+        current.contextKey === next.contextKey &&
+        serializeFilters(current.filters) === serializeFilters(next.filters));
+}
+function serializeFilters(filters) {
+    return JSON.stringify(filters ?? []);
+}
+
 const DEFAULT_AREA_TYPE = 'table';
 const DEFAULT_MODE = 'auto';
 const DEFAULT_TYPE = 'form';
@@ -1791,6 +2009,14 @@ class ClientList {
     inFlightRequestSignatures = new Map();
     fulfilledRequestSignatures = new Map();
     runtimeFilters = new Map();
+    /**
+     * The `propertyKeys` the last table request carried, per item. `undefined`
+     * means the request left the projection to the backend, which is a distinct
+     * state from "not loaded yet" — hence the map rather than a nullable field.
+     */
+    requestPropertyKeys = new Map();
+    /** Single-record read-backs, kept apart from the page loads they must not cancel. */
+    recordSubscriptions = new Map();
     constructor() {
         effect(() => {
             const configs = this.configurations();
@@ -1860,6 +2086,93 @@ class ClientList {
             return;
         this.loadItem(item, true);
     }
+    /**
+     * The query settings this list renders with, shaped as the `returnRecord`
+     * block of a `process-submit` payload. Send it with a create/update so the
+     * backend projects the written record the way this list reads records, then
+     * hand the response to {@link applyWriteResult} — that pair replaces the
+     * full page re-fetch a write used to cost.
+     *
+     * Returns `null` for an informative dashboard (no records to project) or an
+     * unknown key.
+     */
+    getReturnRecordRequest(itemKey) {
+        const item = this.state.itemsByKey()[itemKey];
+        if (!item || item.type !== 'form')
+            return null;
+        const includeState = [...CLIENT_LIST_DEFAULT_INCLUDE_STATE];
+        const culture = this.transloco.getActiveLang();
+        if (item.areaType === 'cards') {
+            return { projection: 'Card', includeState, culture };
+        }
+        const propertyKeys = this.requestPropertyKeys.get(itemKey);
+        return {
+            projection: 'Table',
+            surfaceKey: 'table',
+            includeState,
+            // Omitted, not empty, when the table let the backend pick the
+            // projection — an empty array would read as "no columns".
+            ...(propertyKeys?.length ? { propertyKeys } : {}),
+            culture,
+        };
+    }
+    /**
+     * Applies a create/update to the list in place, without re-fetching the
+     * page. Pass the `process-submit` response as-is.
+     *
+     * Three outcomes, in the order they are tried:
+     * - the write carried a usable record projection → splice it in, no request;
+     * - it did not (`recordProjectionStatus: 'Unavailable'`, or the list has
+     *   nothing to splice into) → read that one record back by id. The write
+     *   already succeeded; this only reads, and never re-submits;
+     * - nothing identifies the record at all → reload the page, as before.
+     *
+     * An approval-queued submit is a no-op: nothing has been written yet.
+     *
+     * Note that the list cannot know where the backend would have sorted a new
+     * record, so an insert lands at the top of the page in view.
+     */
+    applyWriteResult(itemKey, result) {
+        const item = this.state.itemsByKey()[itemKey];
+        if (!item || item.type !== 'form')
+            return;
+        if (this.isPendingApprovalWrite(result))
+            return;
+        const recordId = this.toFiniteNumber(result?.recordId);
+        const record = this.toWriteRecord(result, recordId);
+        if (record) {
+            // A failed splice means the list holds no page to splice into, so
+            // reading the record back would not help either.
+            if (this.state.upsertRecord(itemKey, record, item.config)) {
+                this.afterRecordApplied(itemKey);
+            }
+            else {
+                this.reloadByKey(itemKey);
+            }
+            return;
+        }
+        if (recordId != null) {
+            this.readRecordBack(item, recordId);
+            return;
+        }
+        this.reloadByKey(itemKey);
+    }
+    /**
+     * Drops a deleted record from the list in place. Falls back to a reload when
+     * the record is not part of the loaded set, so a stale list still corrects
+     * itself.
+     */
+    removeRecord(itemKey, recordId) {
+        const item = this.state.itemsByKey()[itemKey];
+        if (!item || item.type !== 'form')
+            return;
+        if (!this.state.removeRecord(itemKey, recordId, item.config)) {
+            this.reloadByKey(itemKey);
+            return;
+        }
+        this.runtimeActions.invalidateRow(itemKey, recordId);
+        this.afterRecordApplied(itemKey, { invalidateRuntimeActions: false });
+    }
     toggleExpanded(key) {
         this.state.toggleExpanded(key);
     }
@@ -2110,6 +2423,89 @@ class ClientList {
             config.onActionExecuted?.(action, ctx);
         }
     }
+    /**
+     * A submit that only queued an approval request has written nothing — the
+     * record it describes does not exist yet, so the list must not move.
+     */
+    isPendingApprovalWrite(result) {
+        return (String(result?.status ?? '')
+            .trim()
+            .toLowerCase() === 'pendingapproval');
+    }
+    /**
+     * The canonical record from a write response, or `null` when there is none
+     * to trust. A backend that has not shipped the canonical projection yet
+     * answers with neither `recordProjectionStatus: 'Available'` nor `values`,
+     * and falls through to the read-back path — which is why this is a plain
+     * shape check and not a parse of alternative record shapes.
+     */
+    toWriteRecord(result, recordId) {
+        if (result?.recordProjectionStatus !== 'Available')
+            return null;
+        const record = result.record;
+        if (!record?.values)
+            return null;
+        const id = this.toFiniteNumber(record.id) ?? recordId;
+        if (id == null)
+            return null;
+        return { ...record, id };
+    }
+    /**
+     * Reads one record back through `fetch/query` with this list's own settings.
+     * Taken when the write could not project the record itself — the write has
+     * already happened, so this reads and never re-submits.
+     */
+    readRecordBack(item, recordId) {
+        const config = item.config;
+        const request = this.getReturnRecordRequest(item.key);
+        if (!request || !this.hasValidIdentifiers(config)) {
+            this.reloadByKey(item.key);
+            return;
+        }
+        // The host's own scope filters plus the record id. Runtime filters (the
+        // search box, a column filter) are deliberately left out: a record the
+        // user just wrote should come back whether or not it matches whatever
+        // they happen to have typed into the list.
+        const filters = [
+            ...config.filters,
+            {
+                key: CLIENT_LIST_RECORD_ID_FILTER_KEY,
+                operator: 'Equals',
+                value: recordId,
+            },
+        ];
+        this.recordSubscriptions.get(item.key)?.unsubscribe();
+        const sub = this.api
+            .getRecord(config.contextKey, request, filters)
+            .subscribe({
+            next: (response) => {
+                this.recordSubscriptions.delete(item.key);
+                const record = response.data?.records?.[0];
+                if (!record || !this.state.upsertRecord(item.key, record, config)) {
+                    this.reloadByKey(item.key);
+                    return;
+                }
+                this.afterRecordApplied(item.key);
+            },
+            error: () => {
+                this.recordSubscriptions.delete(item.key);
+                this.reloadByKey(item.key);
+            },
+        });
+        this.recordSubscriptions.set(item.key, sub);
+    }
+    /**
+     * Runs the tail of a load for a list that changed without one: the row
+     * action cache is stale (a written record's available actions follow its new
+     * state), and hosts hang work off `dataLoaded` / `loaded`.
+     */
+    afterRecordApplied(itemKey, options) {
+        if (options?.invalidateRuntimeActions !== false) {
+            this.runtimeActions.invalidateList(itemKey);
+        }
+        this.notifyDataLoaded(itemKey);
+        this.loaded.emit(itemKey);
+    }
     toRuntimeActionsContext(item, row, config) {
         const recordId = this.resolveRecordId(config, row);
         if (recordId == null)
@@ -2147,6 +2543,9 @@ class ClientList {
     ngOnDestroy() {
         this.subscriptions.forEach((sub) => sub.unsubscribe());
         this.subscriptions.clear();
+        this.recordSubscriptions.forEach((sub) => sub.unsubscribe());
+        this.recordSubscriptions.clear();
+        this.requestPropertyKeys.clear();
         this.rowActionsLoadingFnCache.clear();
         this.runtimeActions.clearAll();
     }
@@ -2184,6 +2583,10 @@ class ClientList {
             const key = config.key ?? this.createItemKey(config, index);
             const existing = previousItems[key];
             const normalizedConfig = this.toNormalizedConfig(config, type, areaType, mode, isPaginated, take, showHeader, collapseEnabled, layout);
+            // Paging is runtime state, not config state: it survives a reconfigure
+            // that changed nothing about the fetch, and the *applied* page size
+            // (the user's rows-per-page choice) is carried forward with it.
+            const keepsPaging = preservesPaging(existing, areaType, normalizedConfig);
             if (isInformative) {
                 return {
                     key,
@@ -2219,12 +2622,13 @@ class ClientList {
                     columns: [],
                     rows: [],
                     cards: [],
-                    // Cards restart from the first page on every reconfigure: the
-                    // loaded set above is wiped, and for infinite scroll `skip` is
-                    // the next offset into that set — carrying it forward would ask
-                    // the backend for page N with nothing before it on screen.
-                    skip: 0,
-                    take,
+                    // For infinite scroll `skip` is the next offset into the loaded
+                    // set, so it travels with that set: kept while the fetch is
+                    // unchanged (the cards themselves are kept too, by
+                    // `mergeItemState`), and restarted at 0 the moment the fetch
+                    // changes and the loaded set stops meaning anything.
+                    skip: keepsPaging ? existing.skip : 0,
+                    take: keepsPaging ? existing.take : take,
                     expanded: existing?.expanded ?? config.collapse?.expandedByDefault ?? true,
                     dashboardData: null,
                     rawData: existing?.rawData ?? null,
@@ -2243,12 +2647,8 @@ class ClientList {
                 columns: [],
                 rows: [],
                 cards: [],
-                skip: existing?.areaType === 'table' &&
-                    existing.config.isPaginated === isPaginated &&
-                    existing.take === take
-                    ? existing.skip
-                    : 0,
-                take,
+                skip: keepsPaging ? existing.skip : 0,
+                take: keepsPaging ? existing.take : take,
                 expanded: existing?.expanded ?? config.collapse?.expandedByDefault ?? true,
                 dashboardData: null,
                 rawData: existing?.rawData ?? null,
@@ -2290,9 +2690,10 @@ class ClientList {
         this.state.setLoading(key, true);
         this.state.setError(key, null);
         const sub = this.api.getRows(config.contextKey, query, filters).subscribe({
-            next: (response) => {
+            next: ({ response, propertyKeys }) => {
                 let hasLoadedData = false;
                 if (response.data) {
+                    this.requestPropertyKeys.set(key, propertyKeys);
                     this.state.setRowsResult(key, response.data, config, query.skip, query.take);
                     this.fulfilledRequestSignatures.set(key, requestSignature);
                     hasLoadedData = true;
@@ -2563,11 +2964,22 @@ class ClientList {
                 this.fulfilledRequestSignatures.delete(key);
             }
         }
+        for (const [key, sub] of this.recordSubscriptions.entries()) {
+            if (!activeKeys.has(key)) {
+                sub.unsubscribe();
+                this.recordSubscriptions.delete(key);
+            }
+        }
         for (const key of this.runtimeFilters.keys()) {
             if (!activeKeys.has(key)) {
                 this.runtimeFilters.delete(key);
             }
         }
+        for (const key of this.requestPropertyKeys.keys()) {
+            if (!activeKeys.has(key)) {
+                this.requestPropertyKeys.delete(key);
+            }
+        }
         for (const key of this.rowActionsLoadingFnCache.keys()) {
             if (!activeKeys.has(key)) {
                 this.rowActionsLoadingFnCache.delete(key);
@@ -2694,5 +3106,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { 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_STATE_KEY, ClientList, ClientListApiService, ClientListRuntimeActionsService, ClientListStateService, ClientListToolbarService, defaultResolveRecordId };
 //# sourceMappingURL=masterteam-client-components-client-list.mjs.map