@mintplayer/ng-spark 22.5.0 → 22.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mintplayer/ng-spark",
   "private": false,
-  "version": "22.5.0",
+  "version": "22.8.0",
   "description": "Angular component library for MintPlayer.Spark CRUD applications",
   "repository": {
     "type": "git",
@@ -84,6 +84,10 @@
     "./services": {
       "types": "./types/mintplayer-ng-spark-services.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-services.mjs"
+    },
+    "./shell": {
+      "types": "./types/mintplayer-ng-spark-shell.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-shell.mjs"
     }
   },
   "type": "module",

package/types/mintplayer-ng-spark-grid.d.ts

@@ -1,6 +1,6 @@
 import { DatatableSettings, BsDatatableFetch } from '@mintplayer/ng-bootstrap/datatable';
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { SparkQuery, EntityType, EntityAttributeDefinition, PersistentObject, LookupReference, CustomActionDefinition } from '@mintplayer/ng-spark/models';
+import { SparkQuery, EntityType, EntityAttributeDefinition, SparkCellColumn, QueryResultItem, QueryColumn, LookupReference, CustomActionDefinition, PersistentObject } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
 import { Type, TemplateRef } from '@angular/core';
 import { HttpErrorResponse } from '@angular/common/http';
@@ -40,37 +40,33 @@ declare function isVirtualScrollingQuery(query: SparkQuery | null): boolean;
  * There is now one grid, {@link SparkQueryGridComponent}, so the drift cannot recur. This stays
  * separate because it is stateless service-shaped logic rather than view state, and because it is
  * what a custom grid would need in order to render Spark cells at all.
- *
- * The constraint that shaped the split still holds and is why the grid takes rows as an input
- * rather than owning a socket: streaming's dependency graph must not reach the bundle of every
- * detail page.
  */
 declare class SparkGridRenderers {
     private readonly registry;
     private readonly sparkService;
-    /** The registered column component for an attribute, or null to fall back to the default cell. */
-    columnComponentFor(attr: EntityAttributeDefinition): Type<any> | null;
+    /** The registered column component for a column, or null to fall back to the default cell. */
+    columnComponentFor(column: SparkCellColumn): Type<any> | null;
     /**
-     * Inputs for a column renderer, filtered to what the component actually declares —
+     * Inputs for a query-grid cell renderer, filtered to what the component actually declares —
      * `NgComponentOutlet` throws on an input the target does not have, which is what lets every
      * member of the renderer contract be optional.
      */
-    columnInputsFor(component: Type<any>, item: PersistentObject, attr: EntityAttributeDefinition): Record<string, any>;
+    columnInputsFor(component: Type<any>, item: QueryResultItem, column: QueryColumn): Record<string, any>;
     /**
-     * The same contract for a row that is not a <see cref="PersistentObject"/>.
+     * The same contract for a row that is not a query result — an AsDetail sub-table row, which is
+     * a plain dictionary of embedded values with no id and no column metadata of its own, so its
+     * value cannot be read the way {@link columnInputsFor} reads one.
      *
-     * An AsDetail row is a plain dictionary — embedded values with no id and no attribute list — so
-     * its value cannot be read the way {@link columnInputsFor} reads one. Only the extraction
-     * differs; the renderer contract is identical, and stating it once is what stops the two from
-     * drifting the way the cell markup already had.
+     * Only the extraction differs; the renderer contract is identical, and stating it once is what
+     * stops the two from drifting the way the cell markup already had.
      */
-    cellInputsFor(component: Type<any>, value: unknown, column: EntityAttributeDefinition, item: unknown): Record<string, any>;
+    cellInputsFor(component: Type<any>, value: unknown, column: SparkCellColumn, item: unknown): Record<string, any>;
     /**
-     * Loads every lookup reference the visible attributes need, in one pass.
+     * Loads every lookup reference the visible columns need, in one pass.
      *
      * Returns an empty map rather than throwing when there are none, so callers never branch on it.
      */
-    loadLookupOptions(attributes: EntityAttributeDefinition[]): Promise<Record<string, LookupReference>>;
+    loadLookupOptions(columns: readonly (SparkCellColumn | EntityAttributeDefinition)[]): Promise<Record<string, LookupReference>>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkGridRenderers, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SparkGridRenderers>;
 }
@@ -243,7 +239,7 @@ declare class SparkQueryGridComponent {
      * default — means "fetch for yourself"; an empty array means "you have been given no rows",
      * which is a different statement and renders an empty grid rather than triggering a load.
      */
-    data: _angular_core.InputSignal<PersistentObject[] | null>;
+    data: _angular_core.InputSignal<QueryResultItem[] | null>;
     /**
      * Server-side search term, passed through to the query.
      *
@@ -251,6 +247,11 @@ declare class SparkQueryGridComponent {
      * host with client-side rows filters them itself before binding `data`.
      */
     search: _angular_core.InputSignal<string>;
+    /**
+     * Column metadata for externally supplied rows. Required whenever `data` is bound, because a
+     * projection cannot describe itself — there is no per-row metadata left to infer it from.
+     */
+    columns: _angular_core.InputSignal<QueryColumn[] | null>;
     /**
      * Change this to re-run the query. Any value works; only its identity matters.
      *
@@ -269,14 +270,35 @@ declare class SparkQueryGridComponent {
      */
     settings: _angular_core.ModelSignal<DatatableSettings>;
     /** Rows the user has ticked. Two-way so chrome outside the grid can read and clear them. */
-    selection: _angular_core.ModelSignal<PersistentObject[]>;
+    selection: _angular_core.ModelSignal<QueryResultItem[]>;
+    /**
+     * Replaces where the first column's link points, per row.
+     *
+     * Return `null` to suppress the link for that row — useful when a grid mixes rows that have a
+     * detail page with rows that do not.
+     *
+     * ⚠️ **It changes the destination, not the permission.** `canRead()` still gates whether any
+     * link is rendered at all, and this function is never consulted when that gate is closed. It
+     * cannot be used to reach a row the rights model withheld; it exists for the case where the
+     * row's natural destination is not `/po/{type}/{id}` — a composed row that maps to a page of
+     * its own, or a grid embedded in a route that owns its own child paths.
+     */
+    rowRoute: _angular_core.InputSignal<((row: QueryResultItem) => unknown[] | null) | null>;
     /** Emitted whenever a load or a page fetch fails, for a host in bespoke chrome. */
     error: _angular_core.OutputEmitterRef<HttpErrorResponse>;
-    rowClicked: _angular_core.OutputEmitterRef<PersistentObject>;
+    rowClicked: _angular_core.OutputEmitterRef<QueryResultItem>;
     customActionExecuted: _angular_core.OutputEmitterRef<{
         action: CustomActionDefinition;
     }>;
     colors: typeof Color;
+    /**
+     * Where the first column's link points for this row: the host's `rowRoute` when it supplied one,
+     * otherwise the row's own detail page.
+     *
+     * A method rather than a computed because the answer is per row, and the template already
+     * iterates rows — a computed would have to be a map keyed by id, rebuilt on every page.
+     */
+    protected rowRouteFor(row: QueryResultItem): unknown[] | null;
     query: _angular_core.WritableSignal<SparkQuery | null>;
     entityType: _angular_core.WritableSignal<EntityType | null>;
     allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
@@ -286,7 +308,7 @@ declare class SparkQueryGridComponent {
     canCreate: _angular_core.WritableSignal<boolean>;
     resultCount: _angular_core.WritableSignal<number | null>;
     customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
-    fetchFn: _angular_core.WritableSignal<BsDatatableFetch<PersistentObject> | null>;
+    fetchFn: _angular_core.WritableSignal<BsDatatableFetch<QueryResultItem> | null>;
     /**
      * Why the component renders its own failure instead of only reporting one.
      *
@@ -299,7 +321,21 @@ declare class SparkQueryGridComponent {
     /** 'none' unless an action is selection-gated, so unaffected grids gain no checkbox column. */
     selectionMode: _angular_core.Signal<_mintplayer_ng_spark_models.SparkSelectionMode>;
     isVirtualScrolling: _angular_core.Signal<boolean>;
-    visibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
+    /**
+     * Columns as sent with the most recent fetched page.
+     *
+     * A host binding `data` (streaming) supplies its own via the `columns` input instead — the
+     * snapshot carries them once, exactly as a paged result does.
+     */
+    private readonly fetchedColumns;
+    /** Every column on the wire, drawn or not — what renderers and lookups resolve against. */
+    allColumns: _angular_core.Signal<QueryColumn[]>;
+    /**
+     * The columns the grid draws. `isVisible: false` ships a value without a column, so a renderer
+     * can read a sibling the grid does not show; undefined means visible, so a server that predates
+     * the field still draws everything.
+     */
+    visibleColumns: _angular_core.Signal<QueryColumn[]>;
     /**
      * True when rows do not come from this component's own fetch.
      *
@@ -348,14 +384,15 @@ declare class SparkQueryGridComponent {
     /**
      * The underlying value a custom renderer receives, which is not the printable one.
      *
-     * `rendererValue` unwraps an AsDetail attribute to the nested object (or objects) rather than
-     * flattening it to text — a renderer for a nested type needs the object, not a summary of it.
+     * A projection is flat, so this is the cell's own value rather than a display string. It is
+     * deliberately not the attribute-shaped `rendererValue`: a query row has no nested object to
+     * fall back to, and reaching for one would hand every renderer `undefined`.
      */
-    rendererValueFor(item: PersistentObject, attr: EntityAttributeDefinition): unknown;
-    getColumnRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;
-    getColumnRendererInputs(component: Type<any>, item: PersistentObject, attr: EntityAttributeDefinition): Record<string, any>;
+    rendererValueFor(item: QueryResultItem, column: QueryColumn): unknown;
+    getColumnRendererComponent(column: QueryColumn): Type<any> | null;
+    getColumnRendererInputs(component: Type<any>, item: QueryResultItem, column: QueryColumn): Record<string, any>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryGridComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryGridComponent, "spark-query-grid", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "search": { "alias": "search"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "settings": { "alias": "settings"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; }, { "settings": "settingsChange"; "selection": "selectionChange"; "error": "error"; "rowClicked": "rowClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryGridComponent, "spark-query-grid", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "search": { "alias": "search"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "settings": { "alias": "settings"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "rowRoute": { "alias": "rowRoute"; "required": false; "isSignal": true; }; }, { "settings": "settingsChange"; "selection": "selectionChange"; "error": "error"; "rowClicked": "rowClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;
 }
 
 /**
@@ -386,7 +423,7 @@ declare class SparkQueryCardComponent {
     parentId: _angular_core.InputSignal<string>;
     parentType: _angular_core.InputSignal<string>;
     reloadToken: _angular_core.InputSignal<unknown>;
-    data: _angular_core.InputSignal<PersistentObject[] | null>;
+    data: _angular_core.InputSignal<QueryResultItem[] | null>;
     search: _angular_core.InputSignal<string>;
     /**
      * Slots forwarded from a host that cannot project content — see the class comment. A card
@@ -396,10 +433,15 @@ declare class SparkQueryCardComponent {
     captionTemplate: _angular_core.InputSignal<TemplateRef<any> | null>;
     actionsTemplate: _angular_core.InputSignal<TemplateRef<any> | null>;
     error: _angular_core.OutputEmitterRef<HttpErrorResponse>;
-    rowClicked: _angular_core.OutputEmitterRef<PersistentObject>;
+    rowClicked: _angular_core.OutputEmitterRef<QueryResultItem>;
     customActionExecuted: _angular_core.OutputEmitterRef<{
         action: CustomActionDefinition;
     }>;
+    /**
+     * Forwarded to the grid. Without this the escape hatch was unreachable from a card — i.e. from
+     * every auto-rendered sub-query and program-unit query page, which is most grids.
+     */
+    rowRoute: _angular_core.InputSignal<((row: QueryResultItem) => unknown[] | null) | null>;
     colors: typeof Color;
     private readonly iconSlots;
     private readonly captionSlots;
@@ -425,9 +467,9 @@ declare class SparkQueryCardComponent {
     /** The caption the card renders unless a slot replaces it. */
     protected readonly caption: _angular_core.Signal<string>;
     protected readonly customActions: _angular_core.Signal<CustomActionDefinition[]>;
-    protected readonly selection: _angular_core.Signal<PersistentObject[]>;
+    protected readonly selection: _angular_core.Signal<QueryResultItem[]>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryCardComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryCardComponent, "spark-query-card", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "search": { "alias": "search"; "required": false; "isSignal": true; }; "iconTemplate": { "alias": "iconTemplate"; "required": false; "isSignal": true; }; "captionTemplate": { "alias": "captionTemplate"; "required": false; "isSignal": true; }; "actionsTemplate": { "alias": "actionsTemplate"; "required": false; "isSignal": true; }; }, { "error": "error"; "rowClicked": "rowClicked"; "customActionExecuted": "customActionExecuted"; }, ["iconSlots", "captionSlots", "actionSlots"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryCardComponent, "spark-query-card", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "search": { "alias": "search"; "required": false; "isSignal": true; }; "iconTemplate": { "alias": "iconTemplate"; "required": false; "isSignal": true; }; "captionTemplate": { "alias": "captionTemplate"; "required": false; "isSignal": true; }; "actionsTemplate": { "alias": "actionsTemplate"; "required": false; "isSignal": true; }; "rowRoute": { "alias": "rowRoute"; "required": false; "isSignal": true; }; }, { "error": "error"; "rowClicked": "rowClicked"; "customActionExecuted": "customActionExecuted"; }, ["iconSlots", "captionSlots", "actionSlots"], never, true, never>;
 }
 
 /**
@@ -461,7 +503,7 @@ declare class SparkQueryCardComponent {
 declare class SparkGridCellComponent {
     private readonly renderers;
     /** The column being rendered. Its `dataType` and `renderer` decide everything below. */
-    column: _angular_core.InputSignal<EntityAttributeDefinition>;
+    column: _angular_core.InputSignal<SparkCellColumn>;
     /**
      * What the caller's value pipe produced: the display text for most columns, and the raw value
      * for `boolean` and `color`, which need the value rather than a rendering of it.

package/types/mintplayer-ng-spark-models.d.ts

@@ -189,7 +189,14 @@ interface EntityType {
     id: string;
     name: string;
     description?: TranslatedString;
-    clrType: string;
+    /**
+     * The backing CLR type, or absent for a JSON-only virtual type (#325).
+     *
+     * Optional on purpose: the server sends null for a virtual type, and this was declared
+     * non-nullable, so any unguarded `.endsWith(...)` on it threw a TypeError naming an innocent
+     * query. Types are data from the wire, not a promise about it.
+     */
+    clrType?: string;
     alias?: string;
     /**
      * Breadcrumb template: literal text plus `{AttributeName}` placeholders. A scalar placeholder
@@ -230,20 +237,142 @@ interface SparkQuery {
     isStreamingQuery?: boolean;
 }
 
+/**
+ * What a query returns: the column metadata once, then one lightweight row per result.
+ *
+ * Rows used to be full `PersistentObject`s, so every row repeated the complete attribute
+ * metadata the client already held from `/spark/types` and never read off the row. More
+ * importantly it conflated two things that are not the same: a **row is a projection**, a
+ * **persistent object is a document**. Nothing here is entitled to act on a row — every
+ * mutating path re-loads by id and re-applies security server-side.
+ */
 interface QueryResult {
-    data: PersistentObject[];
-    totalRecords: number;
+    columns: QueryColumn[];
+    items: QueryResultItem[];
+    /** Rows matching the query after filtering, before paging. */
+    totalItems: number;
     skip: number;
     take: number;
+    typeHints?: Record<string, string>;
+}
+/**
+ * The subset of column metadata a cell needs in order to render.
+ *
+ * Both {@link QueryColumn} (a query result's column) and `EntityAttributeDefinition` (a detail
+ * page's attribute) satisfy this, which is what lets one cell component serve the query grid and
+ * the AsDetail sub-table without either side knowing about the other's shape.
+ */
+interface SparkCellColumn {
+    name: string;
+    label?: TranslatedString;
+    dataType: string;
+    isArray?: boolean;
+    renderer?: string;
+    rendererOptions?: Record<string, any>;
+    referenceType?: string;
+    lookupReferenceType?: string;
+    asDetailType?: string;
+}
+/** One column of a query result, sent once rather than repeated on every row. */
+interface QueryColumn extends SparkCellColumn {
+    order: number;
+    isSortable?: boolean;
+    /**
+     * Whether the grid draws this column. `false` means the row carries the value but no column is
+     * rendered — for a renderer that needs a sibling value (a lock glyph beside a name) without
+     * spending a column on it. `showedOn` decides what ships; this decides what is drawn.
+     */
+    isVisible?: boolean;
+    /** The query backing a Reference column, by name — the client's option source. */
+    query?: string;
+}
+/**
+ * One row: an id, a display string, and a value per column.
+ *
+ * Deliberately too weak to act on — no attribute metadata, no `can` block, no etag, because none
+ * of those can be trusted from a projection.
+ */
+interface QueryResultItem {
+    /** Never null and unique within a result; the server refuses anything else. */
+    id: string;
+    /** What to show when the row is named rather than tabulated (a reference picker's value). */
+    breadcrumb?: string;
+    values: QueryResultItemValue[];
+    /** Presentation hints for the whole row. Keys arrive lower-cased. */
+    typeHints?: Record<string, string>;
+}
+/** One cell. */
+interface QueryResultItemValue {
+    /** The {@link QueryColumn.name} this value belongs to. */
+    key: string;
+    /** Typed JSON, not a string — the server converts on the way out. */
+    value?: any;
+    /** For a reference cell: the target document's id, so a link needs no second lookup. */
+    objectId?: string;
+    /** For a reference cell: the target's display string. */
+    breadcrumb?: string;
+    /** Resolved display labels per referenced id, for a multi-reference cell. */
+    breadcrumbs?: Record<string, string | null>;
+    typeHints?: Record<string, string>;
 }
+/**
+ * Every shape a renderer's `item` can arrive in.
+ *
+ * Three, and they are genuinely different objects rather than variations of one: a query grid hands
+ * a {@link QueryResultItem}, an AsDetail sub-table hands the flat record `nestedPoToDisplayRow`
+ * built, and a detail or form host hands the `PersistentObject` itself. A renderer reused across a
+ * grid and an AsDetail table therefore sees two of them, which is why {@link valueFor} reads all
+ * three rather than making every app write the branch.
+ */
+type SparkRow = QueryResultItem | PersistentObject | Record<string, unknown>;
+/**
+ * The value a row carries for a column, whatever shape the row is in — or `undefined` when it
+ * carries none.
+ *
+ * ```ts
+ * const isPrivate = valueFor(this.item(), 'IsPrivate')?.value === true;
+ * ```
+ *
+ * Always returns the **cell** rather than the bare value, because a reference cell is worth as much
+ * for its `objectId` as for its text, and a helper that discarded it would have to be replaced the
+ * first time a renderer wanted to link somewhere. `?.value` is the cost, once per call site.
+ *
+ * ⚠️ A value only reaches a grid row if its attribute is on the **query surface**. To read a sibling
+ * the grid does not draw, mark it `"showedOn": "Query", "isVisible": false` — shipped, not drawn. An
+ * attribute marked `"showedOn": "PersistentObject"` is absent from a row by design, and this returns
+ * `undefined` for it; that is the first thing to check when a sibling read comes back empty.
+ */
+declare function valueFor(item: SparkRow | null | undefined, columnName: string): QueryResultItemValue | undefined;
+/**
+ * Whether this row is a query result item.
+ *
+ * Discriminated on the *elements*, not just on `Array.isArray(values)`: a flat AsDetail record may
+ * legitimately have a column named `values` holding an array, and mistaking one for the other would
+ * silently read the wrong thing.
+ */
+declare function isQueryRow(row: SparkRow | null | undefined): row is QueryResultItem;
+/** Whether this row is a full persistent object. Discriminated on elements, as above. */
+declare function isPersistentObject(row: SparkRow | null | undefined): row is PersistentObject;
 
 interface ProgramUnit {
     id: string;
     name: TranslatedString;
     icon?: string;
+    /**
+     * Canonical unit type, exact-cased by the server's loader: 'query' | 'persistentObject' | 'url'.
+     * Kept as string rather than a union so an older client tolerates a newer server.
+     */
     type: string;
     queryId?: string;
     persistentObjectId?: string;
+    /**
+     * For a persistentObject unit: the specific object to open — the menu entry deep-links to
+     * `/po/{type}/{objectId}`. Absent means the type's default list. For a composed page this is
+     * whatever stable string the app declared; the server's Actions class may ignore it.
+     */
+    objectId?: string;
+    /** For a url unit: the external address, rendered as a plain anchor (never a router link). */
+    url?: string;
     order: number;
     alias?: string;
 }
@@ -322,13 +451,21 @@ interface CustomActionDefinition {
     offset: number;
 }
 
+/**
+ * The opening message of a stream: the column metadata plus the rows so far.
+ *
+ * Columns arrive once, here. A stream is one result whose rows arrive over time, so its shape is
+ * fixed when it opens — patches carry values only.
+ */
 interface StreamingSnapshotMessage {
     type: 'snapshot';
-    data: PersistentObject[];
+    columns: QueryColumn[];
+    data: QueryResultItem[];
 }
 interface StreamingPatchItem {
     id: string;
-    attributes: Record<string, any>;
+    /** Changed cell values, keyed by column name. Never metadata — the snapshot fixed that. */
+    values: Record<string, any>;
 }
 interface StreamingPatchMessage {
     type: 'patch';
@@ -538,5 +675,5 @@ interface EvaluableAttribute {
  */
 declare function evaluateRules(attr: EvaluableAttribute, value: any): RuleFailure[];
 
-export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, hasShowedOnFlag, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, resolveTranslation, selectionModeFor, selfBreadcrumb };
-export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };
+export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, hasShowedOnFlag, isPersistentObject, isQueryRow, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, resolveTranslation, selectionModeFor, selfBreadcrumb, valueFor };
+export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryColumn, QueryResult, QueryResultItem, QueryResultItemValue, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkCellColumn, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkRow, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };

package/types/mintplayer-ng-spark-pipes.d.ts

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
-import { TranslatedString, PersistentObject, EntityType, LookupReference, EntityAttributeDefinition, ProgramUnit, EntityPermissions, ELookupDisplayType, LookupReferenceValue, ValidationError } from '@mintplayer/ng-spark/models';
+import { TranslatedString, PersistentObject, EntityType, LookupReference, EntityAttributeDefinition, QueryResultItem, ProgramUnit, EntityPermissions, ELookupDisplayType, LookupReferenceValue, ValidationError, QueryColumn } from '@mintplayer/ng-spark/models';
 
 declare class TranslateKeyPipe implements PipeTransform {
     private readonly lang;
@@ -36,7 +36,7 @@ declare class RawAttributeValuePipe implements PipeTransform {
 
 declare class ReferenceDisplayValuePipe implements PipeTransform {
     private readonly lang;
-    transform(attr: EntityAttributeDefinition, formData: Record<string, any>, referenceOptions: Record<string, PersistentObject[]>): string;
+    transform(attr: EntityAttributeDefinition, formData: Record<string, any>, referenceOptions: Record<string, QueryResultItem[]>): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<ReferenceDisplayValuePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<ReferenceDisplayValuePipe, "referenceDisplayValue", true>;
 }
@@ -70,8 +70,16 @@ declare class ReferenceChipsPipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<ReferenceChipsPipe, "referenceChips", true>;
 }
 
+/**
+ * Maps a program unit to the router commands that open it. Type comparisons are exact: the
+ * server's loader canonicalizes `type` casing, so tolerating variants here would only mask a
+ * server that stopped doing so.
+ *
+ * Returns null for a `url` unit — an external address is an `<a href>`, not a router link; the
+ * component rendering the menu owns that branch.
+ */
 declare class RouterLinkPipe implements PipeTransform {
-    transform(unit: ProgramUnit): string[];
+    transform(unit: ProgramUnit): string[] | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<RouterLinkPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<RouterLinkPipe, "routerLink", true>;
 }
@@ -89,7 +97,7 @@ declare class AsDetailColumnsPipe implements PipeTransform {
 }
 
 declare class AsDetailCellValuePipe implements PipeTransform {
-    transform(row: Record<string, any>, parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, PersistentObject[]>>): string;
+    transform(row: Record<string, any>, parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, QueryResultItem[]>>): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<AsDetailCellValuePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<AsDetailCellValuePipe, "asDetailCellValue", true>;
 }
@@ -132,7 +140,7 @@ declare class LookupOptionsPipe implements PipeTransform {
 }
 
 declare class InlineRefOptionsPipe implements PipeTransform {
-    transform(parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, PersistentObject[]>>): PersistentObject[];
+    transform(parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, QueryResultItem[]>>): QueryResultItem[];
     static ɵfac: i0.ɵɵFactoryDeclaration<InlineRefOptionsPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<InlineRefOptionsPipe, "inlineRefOptions", true>;
 }
@@ -163,5 +171,33 @@ declare class ArrayValuePipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<ArrayValuePipe, "arrayValue", true>;
 }
 
-export { ArrayValuePipe, AsDetailCellValuePipe, AsDetailColumnsPipe, AsDetailDisplayValuePipe, AsDetailTypePipe, AttributeValuePipe, CanCreateDetailRowPipe, CanDeleteDetailRowPipe, ErrorForAttributePipe, IconNamePipe, InlineRefOptionsPipe, InputTypePipe, LookupDisplayTypePipe, LookupDisplayValuePipe, LookupOptionsPipe, RawAttributeValuePipe, ReferenceAttrValuePipe, ReferenceChipsPipe, ReferenceDisplayValuePipe, ReferenceLinkRoutePipe, ResolveTranslationPipe, RouterLinkPipe, TranslateKeyPipe };
+/**
+ * The display text of one query-grid cell.
+ *
+ * The attribute-shaped sibling of this ({@link AttributeValuePipe}) still serves detail and edit
+ * pages, which do work in attributes. They are deliberately not one pipe: a query row is a flat
+ * projection with no nested objects and no per-row metadata, so the fallbacks that make sense
+ * there — reaching into `attr.object`, recomputing a breadcrumb template client-side — are not
+ * merely unnecessary here, they are unreachable. Sharing the code would mean carrying branches
+ * that can never fire and inviting the next reader to feed one shape into the other.
+ */
+declare class QueryCellValuePipe implements PipeTransform {
+    transform(column: QueryColumn, item: QueryResultItem | null, lookupRefOptions: Record<string, LookupReference>): any;
+    static ɵfac: i0.ɵɵFactoryDeclaration<QueryCellValuePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<QueryCellValuePipe, "queryCellValue", true>;
+}
+/**
+ * Resolves a multi-reference column (`dataType === 'Reference'`, `isArray === true`) to chips.
+ *
+ * The cell's `value` carries the id array and `breadcrumbs` the server-resolved id → label map,
+ * falling back to the id itself when a label is missing — the same display rule as a single
+ * reference, applied per id.
+ */
+declare class QueryReferenceChipsPipe implements PipeTransform {
+    transform(column: QueryColumn, item: QueryResultItem | null): ReferenceChip[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<QueryReferenceChipsPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<QueryReferenceChipsPipe, "queryReferenceChips", true>;
+}
+
+export { ArrayValuePipe, AsDetailCellValuePipe, AsDetailColumnsPipe, AsDetailDisplayValuePipe, AsDetailTypePipe, AttributeValuePipe, CanCreateDetailRowPipe, CanDeleteDetailRowPipe, ErrorForAttributePipe, IconNamePipe, InlineRefOptionsPipe, InputTypePipe, LookupDisplayTypePipe, LookupDisplayValuePipe, LookupOptionsPipe, QueryCellValuePipe, QueryReferenceChipsPipe, RawAttributeValuePipe, ReferenceAttrValuePipe, ReferenceChipsPipe, ReferenceDisplayValuePipe, ReferenceLinkRoutePipe, ResolveTranslationPipe, RouterLinkPipe, TranslateKeyPipe };
 export type { ReferenceChip };

package/types/mintplayer-ng-spark-po-detail.d.ts

@@ -2,7 +2,7 @@ import * as _angular_core from '@angular/core';
 import { TemplateRef, Type } from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
 import { SparkLanguageService } from '@mintplayer/ng-spark/services';
-import { PersistentObject, EntityType, CustomActionDefinition, LookupReference, EntityAttributeDefinition, AttributeTab, AttributeGroup } from '@mintplayer/ng-spark/models';
+import { PersistentObject, EntityType, CustomActionDefinition, LookupReference, QueryResultItem, EntityAttributeDefinition, AttributeTab, AttributeGroup } from '@mintplayer/ng-spark/models';
 
 declare class SparkPoDetailComponent {
     private readonly route;
@@ -45,7 +45,7 @@ declare class SparkPoDetailComponent {
     item: _angular_core.WritableSignal<PersistentObject | null>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
     asDetailTypes: _angular_core.WritableSignal<Record<string, EntityType>>;
-    asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, PersistentObject[]>>>;
+    asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, QueryResultItem[]>>>;
     type: string;
     id: string;
     canEdit: _angular_core.WritableSignal<boolean>;

package/types/mintplayer-ng-spark-po-form.d.ts

@@ -4,7 +4,7 @@ import { CdkDragDrop } from '@angular/cdk/drag-drop';
 import { Color } from '@mintplayer/ng-bootstrap';
 import { InMemoryTreeSelectProvider, TreeNode } from '@mintplayer/ng-bootstrap/tree-select';
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { PersistentObject, EntityType, ValidationError, RefreshOverlay, LookupReference, EntityAttributeDefinition, EntityPermissions, ELookupDisplayType, EReferenceDisplayType, AttributeTab, AttributeGroup, LookupReferenceValue, RuleFailure } from '@mintplayer/ng-spark/models';
+import { PersistentObject, EntityType, ValidationError, RefreshOverlay, QueryResultItem, LookupReference, EntityAttributeDefinition, EntityPermissions, ELookupDisplayType, EReferenceDisplayType, AttributeTab, AttributeGroup, LookupReferenceValue, RuleFailure } from '@mintplayer/ng-spark/models';
 import { DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
 import { PaginationResponse } from '@mintplayer/pagination';
 
@@ -87,7 +87,7 @@ declare class SparkPoFormComponent {
     refreshOverlay: _angular_core.WritableSignal<RefreshOverlay>;
     isRefreshing: _angular_core.WritableSignal<boolean>;
     colors: typeof Color;
-    referenceOptions: _angular_core.WritableSignal<Record<string, PersistentObject[]>>;
+    referenceOptions: _angular_core.WritableSignal<Record<string, QueryResultItem[]>>;
     referenceProviders: _angular_core.WritableSignal<Record<string, InMemoryTreeSelectProvider>>;
     referenceNodes: _angular_core.WritableSignal<Record<string, Record<string, TreeNode>>>;
     asDetailTypes: _angular_core.WritableSignal<Record<string, EntityType>>;
@@ -97,7 +97,7 @@ declare class SparkPoFormComponent {
     showAsDetailModal: _angular_core.WritableSignal<boolean>;
     editingArrayIndex: _angular_core.WritableSignal<number | null>;
     asDetailPermissions: _angular_core.WritableSignal<Record<string, EntityPermissions>>;
-    asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, PersistentObject[]>>>;
+    asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, QueryResultItem[]>>>;
     ELookupDisplayType: typeof ELookupDisplayType;
     EReferenceDisplayType: typeof EReferenceDisplayType;
     /**
@@ -229,7 +229,7 @@ declare class SparkReferencePickerComponent {
     /** Currently selected referenced id (or null when unset). */
     value: _angular_core.InputSignal<string | null>;
     /** Candidate items to pick from (the full query result, pre-loaded by the parent). */
-    options: _angular_core.InputSignal<PersistentObject[]>;
+    options: _angular_core.InputSignal<QueryResultItem[]>;
     /** Target entity type's CLR type name; used to load the grid's column headers. */
     referenceType: _angular_core.InputSignal<string | undefined>;
     /** Renders the field with the Bootstrap is-invalid state. */
@@ -242,17 +242,17 @@ declare class SparkReferencePickerComponent {
     colors: typeof Color;
     showModal: _angular_core.WritableSignal<boolean>;
     entityType: _angular_core.WritableSignal<EntityType | null>;
-    pagination: _angular_core.WritableSignal<PaginationResponse<PersistentObject> | undefined>;
+    pagination: _angular_core.WritableSignal<PaginationResponse<QueryResultItem> | undefined>;
     settings: _angular_core.WritableSignal<DatatableSettings>;
     searchTerm: string;
     visibleAttributes: _angular_core.Signal<_mintplayer_ng_spark_models.EntityAttributeDefinition[]>;
-    rows: _angular_core.Signal<PersistentObject[]>;
+    rows: _angular_core.Signal<QueryResultItem[]>;
     displayValue: _angular_core.Signal<string>;
     open(): Promise<void>;
     onSearchChange(): void;
     applyFilter(): void;
     clearSearch(): void;
-    select(item: PersistentObject): void;
+    select(item: QueryResultItem): void;
     close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkReferencePickerComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkReferencePickerComponent, "spark-reference-picker", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "referenceType": { "alias": "referenceType"; "required": false; "isSignal": true; }; "isInvalid": { "alias": "isInvalid"; "required": false; "isSignal": true; }; "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;