@masterteam/client-components 0.0.89 → 0.0.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masterteam/client-components",
-  "version": "0.0.89",
+  "version": "0.0.91",
   "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/components": "^0.0.281",
-    "@masterteam/icons": "^0.0.17",
-    "@masterteam/dashboard-builder": "^0.0.86",
-    "@masterteam/forms": "^0.0.146"
+    "@masterteam/components": "^0.0.284",
+    "@masterteam/forms": "^0.0.147",
+    "@masterteam/dashboard-builder": "^0.0.88",
+    "@masterteam/icons": "^0.0.17"
   },
   "dependencies": {
     "tslib": "^2.8.1"

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

@@ -24,6 +24,13 @@ interface Response<T> {
 type ClientListRuntimeContext = string;
 type ClientListFetchStateKey = 'escalation';
 declare 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}.
+ */
+declare const CLIENT_LIST_RECORD_SOURCE_KEY = "__clientListRecordSource";
 /** Record state every list request asks for. */
 declare const CLIENT_LIST_DEFAULT_INCLUDE_STATE: readonly ClientListFetchStateKey[];
 /**
@@ -67,7 +74,23 @@ interface ClientListBaseConfiguration {
 }
 interface ClientListRuntimeRecordActionsContext {
     listKey: string;
+    /**
+     * The context this row's actions belong to: the owning record's context for
+     * a hierarchy row, the list's own context otherwise. In a hierarchy table
+     * the list context is only the aggregation scope and addressing a row
+     * action to it would target the wrong record.
+     */
     contextKey: string | null;
+    /**
+     * The list's own configured context, unchanged. Only differs from
+     * `contextKey` on a hierarchy row.
+     */
+    listContextKey: string | null;
+    /**
+     * The record that owns this row, or null outside a hierarchy table. Its
+     * `levelDataId` is the instance a row action applies to.
+     */
+    source: ClientListFetchRecordSource | null;
     instanceId: number | null;
     moduleId: number;
     row: RuntimeTableDisplayRow;
@@ -135,12 +158,27 @@ interface ClientListTableDisplayConfig {
      * host explicitly opts in with `[]`.
      */
     persistStateExclude?: ClientListTablePersistStateKey[];
+    /**
+     * Column key the table starts grouped by — rows of the same value collapse
+     * under one header, and the column itself stops repeating in every row.
+     *
+     * A starting point, not a lock: the user can regroup or clear it from the
+     * table's own menu, and their choice then survives for the life of the list.
+     * Applied only when the list first appears, so a re-render never yanks the
+     * grouping back from under them.
+     *
+     * The key must name a column that is actually rendered, and grouping only
+     * makes sense once every row of a group is loaded — with backend paging a
+     * group is split across pages and each page grows its own header.
+     */
+    groupBy?: string;
 }
 interface NormalizedClientListTableDisplayConfig {
     pageSize: number;
     searchable: boolean;
     exportable: boolean;
     persistStateExclude: ClientListTablePersistStateKey[];
+    groupBy: string | null;
 }
 interface ClientListFormConfiguration extends ClientListBaseConfiguration {
     type?: 'form';
@@ -153,6 +191,18 @@ interface ClientListFormConfiguration extends ClientListBaseConfiguration {
     instanceId?: number;
     /** Complete filter array forwarded unchanged to `fetch/query`. */
     filters?: ClientListFetchRequestFilter[];
+    /**
+     * `areaType: 'table'` only — fetch the rows owned by this root's
+     * descendants instead of the rows owned by the context's own records. See
+     * {@link ClientListFetchHierarchyScope}. Ignored for cards and informative
+     * lists, which the backend rejects outright.
+     *
+     * Rows then arrive from several owners at once: each carries its owning
+     * record under {@link CLIENT_LIST_RECORD_SOURCE_KEY}, row actions are
+     * addressed to that owner's context, and `state.totals` / `state.sourceGroups`
+     * carry the pre-pagination aggregates.
+     */
+    hierarchy?: ClientListFetchHierarchyScope;
     mode?: ClientListMode;
     columnKeys?: string[];
     /**
@@ -231,6 +281,31 @@ interface ClientListFetchRequestFilter {
 interface ClientListFetchRequestDisplay {
     areas: string[];
 }
+/**
+ * Descendant scope for a `Table` request: instead of the rows owned by the
+ * context's own records, fetch the rows owned by a root record's descendants,
+ * combined across every child level the user may read.
+ *
+ * Backend constraints, all of them hard errors rather than silent fallbacks:
+ * `Table` projection only, in a `level:<id>/module:<id>` context backed by
+ * ModuleData, and never combined with tree/selector/process-context requests.
+ * The root is only reachable when `rootId` belongs to the level in
+ * `contextKey`.
+ *
+ * Do not also send a `levelDataId` filter naming the root — that filter still
+ * means "owned by this record" and would strip the descendants back out.
+ */
+interface ClientListFetchHierarchyScope {
+    /** Level-data record id of the root, not a module record id. */
+    rootId: number;
+    /**
+     * `-1` (default) every descendant, `1` direct children only, `0` none.
+     * Other negative values are rejected by the backend.
+     */
+    depth?: number;
+    /** Also include rows owned by the root itself. Defaults to `false`. */
+    includeRoot?: boolean;
+}
 interface ClientListFetchQueryRequest {
     contextKey: string;
     projection: ClientListFetchProjection;
@@ -241,6 +316,7 @@ interface ClientListFetchQueryRequest {
     pageSize?: number;
     surfaceKey?: string;
     display?: ClientListFetchRequestDisplay;
+    hierarchy?: ClientListFetchHierarchyScope;
 }
 /**
  * The query settings a list renders with, in the shape `process-submit` takes
@@ -322,9 +398,15 @@ interface ClientListFetchRecordState {
 interface ClientListFetchRecord {
     id: number;
     name?: string;
+    /**
+     * In a hierarchy response this is the *module* schema for every row, not the
+     * owning level — read `source.levelId` for that.
+     */
     schemaId?: number;
     values: Record<string, ClientListFetchValueCell>;
     state?: ClientListFetchRecordState | null;
+    /** Hierarchy responses only: the record that owns this row. */
+    source?: ClientListFetchRecordSource | null;
 }
 interface ClientListFetchSchema {
     id: number;
@@ -340,6 +422,64 @@ interface ClientListFetchCatalog {
      * keyed by the owning property key (e.g. a `LookupModuleCheckList`).
      */
     nestedProperties?: Record<string, ClientListFetchPropertyMeta[]>;
+    /**
+     * Hierarchy responses only: one catalog per owning child context, keyed by
+     * `record.source.contextKey`. Each carries that level's own property ids,
+     * configurations and overrides — which is what an edit of that row has to
+     * be built from. The top-level `properties` describe the shared columns and
+     * are normalized across levels, so they cannot stand in for these.
+     *
+     * Note every entry's `schemaId` is the *module* schema, the same for all of
+     * them; the owning level is `record.source.levelId`, never this.
+     */
+    byContext?: Record<string, ClientListFetchCatalog>;
+}
+/**
+ * The record that actually owns a row in a hierarchy response. The list's own
+ * context is only the aggregation scope, so this — not the list config — is
+ * what a row action, an edit, or a navigation has to be addressed to.
+ */
+interface ClientListFetchRecordSource {
+    levelDataId: number;
+    levelId: number;
+    name: string;
+    levelName: string;
+    contextKey: string;
+}
+/**
+ * One aggregate over every matching row before pagination — not just the
+ * current page.
+ */
+interface ClientListFetchSum {
+    propertyKey: string;
+    /** Backend decimal sum of the numeric raw values. */
+    value: number;
+    /** How many rows contributed, valid zeroes included. */
+    valueCount: number;
+    /**
+     * Rows whose value was missing or non-numeric. Greater than zero means the
+     * total is incomplete and must be presented as such — see
+     * {@link isClientListTotalIncomplete}.
+     */
+    missingValueCount: number;
+}
+/**
+ * Rows grouped by their owning record. Groups are per *actual* owner at any
+ * depth: a grandchild's rows appear once under the grandchild, never repeated
+ * under the levels in between.
+ */
+interface ClientListFetchSourceGroup {
+    source: ClientListFetchRecordSource;
+    /**
+     * Only this group's row ids **on the current page** — may be empty while
+     * `totalCount` and `totals` are non-zero, because an owner's rows can span
+     * pages.
+     */
+    recordIds: number[];
+    /** Every matching row for this owner, across all pages. */
+    totalCount: number;
+    /** Subtotals over all of this owner's matching rows, across all pages. */
+    totals: ClientListFetchSum[];
 }
 interface ClientListFetchTableColumn {
     key: string;
@@ -365,6 +505,17 @@ interface ClientListFetchProjectionMeta {
     columns?: ClientListFetchTableColumn[];
     displayOrder?: ClientListFetchCardDisplayOrderItem[];
     groups?: ClientListFetchCardGroup[];
+    /** Hierarchy responses only: per-owner groups, subtotals and page row ids. */
+    sourceGroups?: ClientListFetchSourceGroup[];
+    /**
+     * Hierarchy responses only: totals over every matching row before
+     * pagination. The backend fills this from the module's configured summary
+     * keys, which today means a single `amount` entry on the financial module
+     * and an **empty array everywhere else** — so this being present says
+     * nothing about which keys are in it. Always look an entry up by key with
+     * {@link findClientListTotal}; never read `totals[0]`.
+     */
+    totals?: ClientListFetchSum[];
 }
 interface ClientListFetchQueryResponse {
     contextKey: string;
@@ -460,6 +611,17 @@ interface ClientListBaseState {
     expanded: boolean;
     dashboardData: DashboardBuilderData | null;
     rawData: unknown | null;
+    /**
+     * Hierarchy tables only: totals over every matching row before pagination,
+     * so they stay put as the user pages. Undefined for an ordinary list — the
+     * backend sends none, and a page sum would not be the same number.
+     */
+    totals?: ClientListFetchSum[];
+    /**
+     * Hierarchy tables only: one entry per owning record, with its full matching
+     * count and subtotals plus the ids of its rows on the current page.
+     */
+    sourceGroups?: ClientListFetchSourceGroup[];
 }
 interface ClientListTableState extends ClientListBaseState {
     type: 'form';
@@ -485,6 +647,8 @@ interface NormalizedClientListConfiguration {
     contextKey: ClientListRuntimeContext | null;
     instanceId: number | null;
     filters: ClientListFetchRequestFilter[];
+    /** Null unless the host asked for descendant scope on a table. */
+    hierarchy: ClientListFetchHierarchyScope | null;
     levelId: number | null;
     moduleId: number;
     type: ClientListType;
@@ -556,8 +720,9 @@ declare class ClientListStateService {
     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.
+     * `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: string, recordId: number, config: NormalizedClientListConfiguration): boolean;
     private upsertRowRecord;
@@ -756,6 +921,14 @@ declare class ClientList implements OnDestroy {
     private resolveAreaType;
     private resolveType;
     private resolveMode;
+    /**
+     * 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.
+     */
+    private resolveHierarchyScope;
     private toNormalizedConfig;
     private createItemKey;
     private resolveLayout;
@@ -777,11 +950,43 @@ declare class ClientList implements OnDestroy {
     private asInformativeConfig;
     private asFormConfig;
     private serializeFilters;
+    private serializeHierarchy;
     private resolveFetchFilters;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientList, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ClientList, "mt-client-list", never, { "configurations": { "alias": "configurations"; "required": true; "isSignal": true; }; "defaultTake": { "alias": "defaultTake"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "errored": "errored"; "itemClicked": "itemClicked"; }, never, never, true, never>;
 }
 
+/**
+ * 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.
+ */
+declare function readClientListRowSource(row: RuntimeTableDisplayRow | null | undefined): ClientListFetchRecordSource | 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.
+ */
+declare function findClientListTotal(totals: readonly ClientListFetchSum[] | null | undefined, propertyKey: string): ClientListFetchSum | 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.
+ */
+declare function isClientListTotalIncomplete(total: ClientListFetchSum | null | undefined): boolean;
+/**
+ * The subtotal group for one owning record, by its level-data id.
+ */
+declare function findClientListSourceGroup(groups: readonly ClientListFetchSourceGroup[] | null | undefined, levelDataId: number): ClientListFetchSourceGroup | null;
+
 declare class ClientListApiService {
     private readonly http;
     private readonly runtimeFetchBaseUrl;
@@ -791,12 +996,18 @@ declare 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: ClientListRuntimeContext, query: ClientListTableQuery, filters?: ClientListFetchRequestFilter[]): Observable<ClientListRowsFetchResult>;
+    getRows(contextKey: ClientListRuntimeContext, query: ClientListTableQuery, filters?: ClientListFetchRequestFilter[], hierarchy?: ClientListFetchHierarchyScope | null): 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.
+     *
+     * `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: ClientListRuntimeContext, request: ClientListReturnRecordRequest, filters: ClientListFetchRequestFilter[]): Observable<Response<ClientListFetchQueryResponse>>;
     getCards(contextKey: ClientListRuntimeContext, filters?: ClientListFetchRequestFilter[], skip?: number, take?: number): Observable<Response<ClientListCardsPayload>>;
@@ -804,6 +1015,14 @@ declare class ClientListApiService {
     private queryRuntime;
     private resolveTablePropertyKeys;
     private toPage;
+    /**
+     * 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.
+     */
+    private toHierarchyScope;
     private toEffectiveColumnKeys;
     private readTableSettingsContext;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientListApiService, never>;
@@ -856,8 +1075,19 @@ interface ClientListToolbarBucket {
     filters: WritableSignal<TableFilters>;
     filterTerm: WritableSignal<string>;
     groupBy: WritableSignal<string | null>;
+    /**
+     * Sort mirrored into `mt-table`. PrimeNG only renders group headers while
+     * the sort field *is* the grouped column, so a grouped list has to carry the
+     * matching sort or it silently renders as an ordinary flat table.
+     */
+    sortField: WritableSignal<string | null>;
+    sortDirection: WritableSignal<'asc' | 'desc' | null>;
     activeTab: WritableSignal<any>;
 }
+/** Initial toolbar state, applied only when a bucket is first created. */
+interface ClientListToolbarDefaults {
+    groupBy?: string | null;
+}
 /**
  * Per-list toolbar state holder. Buckets are keyed by list `key` (see
  * `ClientListBaseState.key`) so switching between table and cards for the same
@@ -867,11 +1097,24 @@ interface ClientListToolbarBucket {
  */
 declare class ClientListToolbarService {
     private readonly buckets;
-    forList(key: string): ClientListToolbarBucket;
+    /**
+     * Lists whose defaults have been applied. Tracked apart from the bucket
+     * itself because the bucket can be created by whichever view renders first —
+     * the cards view asks for one without defaults — and seeding on creation
+     * alone would then lose them for good.
+     */
+    private readonly seeded;
+    /**
+     * `defaults` are applied once per list and ignored on every later call.
+     * Re-applying them would fight the user: a host that asks for an initial
+     * grouping would otherwise re-impose it on each render, so regrouping or
+     * clearing it from the table menu would never stick.
+     */
+    forList(key: string, defaults?: ClientListToolbarDefaults): ClientListToolbarBucket;
     clear(key: string): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientListToolbarService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ClientListToolbarService>;
 }
 
-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 };
+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 };
+export type { ClientListAreaType, ClientListBaseConfiguration, ClientListBaseState, ClientListCard, ClientListCardModule, ClientListCardProperty, ClientListCardsPayload, ClientListCardsState, ClientListClickableItem, ClientListCollapseConfig, ClientListConfiguration, ClientListContentTemplateContext, ClientListDataLoadedHandler, ClientListFetchCardDisplayOrderItem, ClientListFetchCardGroup, ClientListFetchCatalog, ClientListFetchHierarchyScope, ClientListFetchProjection, ClientListFetchProjectionMeta, ClientListFetchPropertyMeta, ClientListFetchQueryRequest, ClientListFetchQueryResponse, ClientListFetchRecord, ClientListFetchRecordSource, ClientListFetchRecordState, ClientListFetchRequestDisplay, ClientListFetchRequestFilter, ClientListFetchSchema, ClientListFetchSourceGroup, ClientListFetchStateKey, ClientListFetchSum, 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, ClientListToolbarDefaults, ClientListType, NormalizedClientListConfiguration, NormalizedClientListTableDisplayConfig, Response, RuntimeEntityColumnDef, RuntimeTableDisplayRow, RuntimeTableRowsResponse };