@masterteam/client-components 0.0.85 → 0.0.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masterteam/client-components",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "publishConfig": {
     "directory": "../../../dist/masterteam/client-components",
     "linkDirectory": true,
@@ -16,10 +16,10 @@
     "rxjs": "^7.8.2",
     "tailwindcss": "^4.2.2",
     "tailwindcss-primeui": "^0.6.1",
-    "@masterteam/forms": "^0.0.138",
-    "@masterteam/dashboard-builder": "^0.0.80",
+    "@masterteam/forms": "^0.0.140",
     "@masterteam/icons": "^0.0.17",
-    "@masterteam/components": "^0.0.274"
+    "@masterteam/components": "^0.0.274",
+    "@masterteam/dashboard-builder": "^0.0.81"
   },
   "dependencies": {
     "tslib": "^2.8.1"

package/types/masterteam-client-components-client-list.d.ts

@@ -24,6 +24,14 @@ interface Response<T> {
 type ClientListRuntimeContext = string;
 type ClientListFetchStateKey = 'escalation';
 declare const CLIENT_LIST_RECORD_STATE_KEY = "__clientListRecordState";
+/** Record state every list request asks for. */
+declare const CLIENT_LIST_DEFAULT_INCLUDE_STATE: readonly ClientListFetchStateKey[];
+/**
+ * `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.
+ */
+declare const CLIENT_LIST_RECORD_ID_FILTER_KEY = "id";
 interface ClientListBaseConfiguration {
     key?: string;
     title?: string;
@@ -234,6 +242,48 @@ interface ClientListFetchQueryRequest {
     surfaceKey?: string;
     display?: ClientListFetchRequestDisplay;
 }
+/**
+ * The query settings a list renders with, in the shape `process-submit` takes
+ * as `returnRecord`. Sending these with a write asks the backend to project
+ * the written record exactly the way this list would have fetched it, so the
+ * list can splice the result straight in.
+ *
+ * The same object doubles as the spec for reading a single record back through
+ * `fetch/query` when the write could not project one — one description of
+ * "how this list reads a record", used by both paths so they cannot drift.
+ */
+interface ClientListReturnRecordRequest {
+    projection: ClientListFetchProjection;
+    surfaceKey?: string;
+    includeState?: ClientListFetchStateKey[];
+    propertyKeys?: string[];
+    culture?: string;
+}
+type ClientListRecordProjectionStatus = 'Available' | 'Unavailable';
+/**
+ * The part of a `process-submit` response a list needs to apply a write
+ * locally. Structural on purpose: `ProcessFormSubmitResponse` from
+ * `@masterteam/forms/client-form` satisfies it, and so does any host-owned
+ * envelope that carries the same three keys.
+ */
+interface ClientListRecordWriteResult {
+    /** `PendingApproval` writes nothing yet — the list must stay as it is. */
+    status?: string | null;
+    recordId?: number | string | null;
+    record?: ClientListFetchRecord | null;
+    recordProjectionStatus?: ClientListRecordProjectionStatus | string | null;
+}
+/**
+ * A table page plus the `propertyKeys` the request actually carried. The keys
+ * are not derivable from the response — the backend echoes columns, not the
+ * projection it was asked for — and `returnRecord` has to repeat them
+ * verbatim, so the request reports them.
+ */
+interface ClientListRowsFetchResult {
+    response: Response<RuntimeTableRowsResponse>;
+    /** `undefined` when the request left the projection to the backend. */
+    propertyKeys?: string[];
+}
 interface ClientListTableSettingsColumn {
     key?: string;
     propertyKey?: string;
@@ -487,6 +537,40 @@ declare class ClientListStateService {
     setTablePaging(key: string, skip: number, take: number): void;
     setRowsResult(key: string, response: RuntimeTableRowsResponse, config: NormalizedClientListConfiguration, skip: number, take: number): void;
     setCardsResult(key: string, response: ClientListCardsPayload, config: NormalizedClientListConfiguration, skip?: number, take?: number, append?: boolean): void;
+    /**
+     * 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: string, record: ClientListFetchRecord, config: NormalizedClientListConfiguration): boolean;
+    /**
+     * 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: string, recordId: number, config: NormalizedClientListConfiguration): boolean;
+    private upsertRowRecord;
+    private upsertCardRecord;
+    /**
+     * 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.
+     */
+    private mergeRecord;
+    private withRecords;
+    private patchItem;
     /**
      * 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
@@ -539,6 +623,14 @@ declare class ClientList implements OnDestroy {
     private readonly inFlightRequestSignatures;
     private readonly fulfilledRequestSignatures;
     private readonly runtimeFilters;
+    /**
+     * 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.
+     */
+    private readonly requestPropertyKeys;
+    /** Single-record read-backs, kept apart from the page loads they must not cancel. */
+    private readonly recordSubscriptions;
     constructor();
     onLazyLoad(itemKey: string, event: ClientListLazyLoadEvent): void;
     /**
@@ -556,6 +648,40 @@ declare class ClientList implements OnDestroy {
     loadMoreCards(itemKey: string): void;
     reload(itemKey?: string): void;
     reloadByKey(itemKey: string): void;
+    /**
+     * 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: string): ClientListReturnRecordRequest | null;
+    /**
+     * 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: string, result: ClientListRecordWriteResult | null | undefined): void;
+    /**
+     * 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: string, recordId: number): void;
     toggleExpanded(key: string): void;
     onTableRowClick(item: ClientListState, row: RuntimeTableDisplayRow): void;
     onCardClick(item: ClientListState, card: ClientListCard): void;
@@ -592,6 +718,31 @@ declare class ClientList implements OnDestroy {
     private normalizeActionKey;
     private toFiniteNumber;
     private executeRuntimeAction;
+    /**
+     * 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.
+     */
+    private isPendingApprovalWrite;
+    /**
+     * 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.
+     */
+    private toWriteRecord;
+    /**
+     * 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.
+     */
+    private readRecordBack;
+    /**
+     * 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`.
+     */
+    private afterRecordApplied;
     private toRuntimeActionsContext;
     private resolveRecordId;
     templateContext(item: ClientListState): ClientListContentTemplateContext;
@@ -635,7 +786,19 @@ declare class ClientListApiService {
     private readonly http;
     private readonly runtimeFetchBaseUrl;
     private readonly informativeBaseUrl;
-    getRows(contextKey: ClientListRuntimeContext, query: ClientListTableQuery, filters?: ClientListFetchRequestFilter[]): Observable<Response<RuntimeTableRowsResponse>>;
+    /**
+     * 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: ClientListRuntimeContext, query: ClientListTableQuery, filters?: ClientListFetchRequestFilter[]): Observable<ClientListRowsFetchResult>;
+    /**
+     * 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: ClientListRuntimeContext, request: ClientListReturnRecordRequest, filters: ClientListFetchRequestFilter[]): Observable<Response<ClientListFetchQueryResponse>>;
     getCards(contextKey: ClientListRuntimeContext, filters?: ClientListFetchRequestFilter[], skip?: number, take?: number): Observable<Response<ClientListCardsPayload>>;
     getInformativeDashboard(levelId: number, moduleId: number): Observable<Response<ClientListInformativeDashboardPayload>>;
     private queryRuntime;
@@ -710,5 +873,5 @@ declare class ClientListToolbarService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ClientListToolbarService>;
 }
 
-export { CLIENT_LIST_RECORD_STATE_KEY, ClientList, ClientListApiService, ClientListRuntimeActionsService, ClientListStateService, ClientListToolbarService, defaultResolveRecordId };
-export type { ClientListAreaType, ClientListBaseConfiguration, ClientListBaseState, ClientListCard, ClientListCardModule, ClientListCardProperty, ClientListCardsPayload, ClientListCardsState, ClientListClickableItem, ClientListCollapseConfig, ClientListConfiguration, ClientListContentTemplateContext, ClientListDataLoadedHandler, ClientListFetchCardDisplayOrderItem, ClientListFetchCardGroup, ClientListFetchCatalog, ClientListFetchProjection, ClientListFetchProjectionMeta, ClientListFetchPropertyMeta, ClientListFetchQueryRequest, ClientListFetchQueryResponse, ClientListFetchRecord, ClientListFetchRecordState, ClientListFetchRequestDisplay, ClientListFetchRequestFilter, ClientListFetchSchema, ClientListFetchStateKey, ClientListFetchTableColumn, ClientListFetchValueCell, ClientListFormConfiguration, ClientListInformativeChartLink, ClientListInformativeConfiguration, ClientListInformativeDashboardPayload, ClientListInformativeState, ClientListItemClickedEvent, ClientListLayoutConfig, ClientListLazyLoadEvent, ClientListMode, ClientListRecordEscalationState, ClientListRuntimeContext, ClientListRuntimeRecordActionsConfig, ClientListRuntimeRecordActionsContext, ClientListState, ClientListTableDisplayConfig, ClientListTablePersistStateKey, ClientListTableQuery, ClientListTableSettingsCatalogResponse, ClientListTableSettingsColumn, ClientListTableState, ClientListTableTransform, ClientListTableTransformResult, ClientListToolbarBucket, ClientListType, NormalizedClientListConfiguration, NormalizedClientListTableDisplayConfig, Response, RuntimeEntityColumnDef, RuntimeTableDisplayRow, RuntimeTableRowsResponse };
+export { CLIENT_LIST_DEFAULT_INCLUDE_STATE, CLIENT_LIST_RECORD_ID_FILTER_KEY, CLIENT_LIST_RECORD_STATE_KEY, ClientList, ClientListApiService, ClientListRuntimeActionsService, ClientListStateService, ClientListToolbarService, defaultResolveRecordId };
+export type { ClientListAreaType, ClientListBaseConfiguration, ClientListBaseState, ClientListCard, ClientListCardModule, ClientListCardProperty, ClientListCardsPayload, ClientListCardsState, ClientListClickableItem, ClientListCollapseConfig, ClientListConfiguration, ClientListContentTemplateContext, ClientListDataLoadedHandler, ClientListFetchCardDisplayOrderItem, ClientListFetchCardGroup, ClientListFetchCatalog, ClientListFetchProjection, ClientListFetchProjectionMeta, ClientListFetchPropertyMeta, ClientListFetchQueryRequest, ClientListFetchQueryResponse, ClientListFetchRecord, ClientListFetchRecordState, ClientListFetchRequestDisplay, ClientListFetchRequestFilter, ClientListFetchSchema, ClientListFetchStateKey, ClientListFetchTableColumn, ClientListFetchValueCell, ClientListFormConfiguration, ClientListInformativeChartLink, ClientListInformativeConfiguration, ClientListInformativeDashboardPayload, ClientListInformativeState, ClientListItemClickedEvent, ClientListLayoutConfig, ClientListLazyLoadEvent, ClientListMode, ClientListRecordEscalationState, ClientListRecordProjectionStatus, ClientListRecordWriteResult, ClientListReturnRecordRequest, ClientListRowsFetchResult, ClientListRuntimeContext, ClientListRuntimeRecordActionsConfig, ClientListRuntimeRecordActionsContext, ClientListState, ClientListTableDisplayConfig, ClientListTablePersistStateKey, ClientListTableQuery, ClientListTableSettingsCatalogResponse, ClientListTableSettingsColumn, ClientListTableState, ClientListTableTransform, ClientListTableTransformResult, ClientListToolbarBucket, ClientListType, NormalizedClientListConfiguration, NormalizedClientListTableDisplayConfig, Response, RuntimeEntityColumnDef, RuntimeTableDisplayRow, RuntimeTableRowsResponse };