@mintplayer/ng-spark 22.2.0 → 22.4.0

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

@@ -0,0 +1,499 @@
+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 * as _angular_core from '@angular/core';
+import { Type, TemplateRef } from '@angular/core';
+import { HttpErrorResponse } from '@angular/common/http';
+import { Color } from '@mintplayer/ng-bootstrap';
+import { SparkLanguageService } from '@mintplayer/ng-spark/services';
+import { ReferenceChip } from '@mintplayer/ng-spark/pipes';
+
+/** Page sizes offered by every Spark grid. */
+declare const SPARK_GRID_PAGE_SIZES: number[];
+/**
+ * The attributes a grid shows, in display order.
+ *
+ * Shared so the two grids cannot disagree about what "visible" means — they each had their own
+ * copy of this expression, which is the kind of thing that stays identical right up until it
+ * doesn't.
+ */
+declare function visibleGridAttributes(entityType: EntityType | null): EntityAttributeDefinition[];
+/**
+ * Initial datatable settings for a query, seeded with the query's declared sort.
+ *
+ * The datatable owns paging and sorting from here on and calls the fetch callback per page; this
+ * only decides where it starts.
+ */
+declare function initialGridSettings(query: SparkQuery | null): DatatableSettings;
+/** Whether a query renders as a virtual-scrolling grid rather than a paged one. */
+declare function isVirtualScrollingQuery(query: SparkQuery | null): boolean;
+
+/**
+ * Renderer lookup and lookup-reference loading for a Spark grid.
+ *
+ * This was extracted when `spark-query-list` and `spark-sub-query` were two components holding
+ * byte-identical copies of it — around 120 lines between them. That duplication was not a
+ * tidiness complaint: it produced drift. The two copies disagreed about `[indeterminate]`, about
+ * resetting permission state, about whether a fetch failure surfaces or is swallowed, and about
+ * virtual-scroll sizing — four user-visible bugs, each fixed on one side and not the other.
+ *
+ * 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;
+    /**
+     * Inputs for a column 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>;
+    /**
+     * The same contract for a row that is not a <see cref="PersistentObject"/>.
+     *
+     * 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.
+     */
+    cellInputsFor(component: Type<any>, value: unknown, column: EntityAttributeDefinition, item: unknown): Record<string, any>;
+    /**
+     * Loads every lookup reference the visible attributes 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>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkGridRenderers, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<SparkGridRenderers>;
+}
+
+/**
+ * Header slots for `<spark-query-card>`.
+ *
+ * Each directive marks a template that REPLACES one region of the card header. Supplying one
+ * leaves the other two alone — that is the whole point of having three rather than the single
+ * whole-header template they replace, where changing the icon meant re-implementing the caption
+ * and the action bar as well.
+ *
+ * An omitted slot is not an empty slot: the card renders its default. This is what keeps the
+ * auto-rendered sub-query working. A sub-query is rendered from `EntityTypeDefinition.Queries`
+ * with no host to project into, so a mechanism that only ever REPLACED chrome would leave that
+ * call site with nothing — which is why an earlier design had the query declare its own chrome
+ * server-side. Overriding a default needs no host; replacing one does.
+ *
+ * The two ends of that are visible in the defaults themselves. Neither `SparkQuery` nor
+ * `EntityType` carries an icon, so the server has nothing to say and the slot is the only
+ * source. Actions are the mirror image: the server declares them per type, so the default is
+ * the real answer and the slot is a rare override.
+ *
+ * Naming follows ng-bootstrap's `*bsDatatableColumn` convention — prefix, component, slot —
+ * with `spark`, since these are ng-spark directives and `bs` is another package's prefix. These
+ * are the first attribute directives in ng-spark; every existing selector is an element.
+ *
+ * ## Targeting one query
+ *
+ * Each slot takes an optional query alias or id as its value. A detail page renders one card per
+ * entry in `EntityTypeDefinition.Queries`, so a host that supplies a bare slot would decorate
+ * every one of them identically — rarely what is wanted. A targeted slot applies to that query;
+ * an untargeted one is the fallback for the rest.
+ *
+ * ```html
+ * <span *sparkQueryIcon="'cars'"><spark-icon name="car-front" /></span>
+ * <span *sparkQueryIcon><spark-icon name="table" /></span>
+ * ```
+ *
+ * Matching is case-insensitive, against the query's alias and then its id. This is the
+ * `bsPriorityNavItem` shape: a value input aliased to the selector, collected with
+ * `contentChildren`.
+ */
+/** Resolves a slot list to the one that applies to a query: targeted first, then untargeted. */
+declare function slotFor<T extends {
+    forQuery: () => string;
+}>(slots: readonly T[], query: SparkQuery | null): T | null;
+/**
+ * The icon at the header's leading edge. No default: nothing in the model describes one.
+ *
+ * ```html
+ * <spark-query-card [queryId]="'cars'">
+ *   <spark-icon *sparkQueryIcon name="car-front" />
+ * </spark-query-card>
+ * ```
+ */
+declare class SparkQueryIconDirective {
+    readonly templateRef: TemplateRef<SparkQuerySlotContext>;
+    /** Query alias or id this slot applies to. Empty targets every query on the page. */
+    readonly forQuery: _angular_core.InputSignal<string>;
+    static ngTemplateContextGuard(_dir: SparkQueryIconDirective, ctx: unknown): ctx is SparkQuerySlotContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryIconDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkQueryIconDirective, "[sparkQueryIcon]", never, { "forQuery": { "alias": "sparkQueryIcon"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * The header caption. Defaults to the query's translated description, falling back to its name.
+ *
+ * The context carries that resolved default as `$implicit`, so a host can decorate it — add a
+ * count, a badge — without re-resolving the translation itself.
+ */
+declare class SparkQueryCaptionDirective {
+    readonly templateRef: TemplateRef<SparkQueryCaptionContext>;
+    readonly forQuery: _angular_core.InputSignal<string>;
+    static ngTemplateContextGuard(_dir: SparkQueryCaptionDirective, ctx: unknown): ctx is SparkQueryCaptionContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryCaptionDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkQueryCaptionDirective, "[sparkQueryCaption]", never, { "forQuery": { "alias": "sparkQueryCaption"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * The buttons at the header's trailing edge. Defaults to the server-declared custom actions.
+ *
+ * The context carries those actions and the current selection, so a host that wants its own
+ * buttons ALONGSIDE the server's can render both rather than choosing. Without that, overriding
+ * this slot to add one button would silently drop every action the type declares — and the
+ * server's actions are the ones carrying `selectionRule` and the permission filter.
+ *
+ * ```html
+ * <ng-container *sparkQueryActions="let actions; selection as rows">
+ *   <button (click)="export(rows)">Export</button>
+ * </ng-container>
+ * ```
+ */
+declare class SparkQueryActionsDirective {
+    readonly templateRef: TemplateRef<SparkQueryActionsContext>;
+    readonly forQuery: _angular_core.InputSignal<string>;
+    static ngTemplateContextGuard(_dir: SparkQueryActionsDirective, ctx: unknown): ctx is SparkQueryActionsContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryActionsDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkQueryActionsDirective, "[sparkQueryActions]", never, { "forQuery": { "alias": "sparkQueryActions"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Context for the icon slot: the query whose card is being rendered. */
+declare class SparkQuerySlotContext {
+    $implicit: SparkQuery | null;
+}
+declare class SparkQueryCaptionContext {
+    /** The caption the card would have rendered: description, or the query name. */
+    $implicit: string;
+    query: SparkQuery | null;
+}
+declare class SparkQueryActionsContext {
+    /** The custom actions the card would have rendered, already filtered for this query. */
+    $implicit: CustomActionDefinition[];
+    /** Rows currently ticked. Empty unless an action is selection-gated. */
+    selection: PersistentObject[];
+    query: SparkQuery | null;
+}
+
+/**
+ * The one Spark grid: a `<bs-datatable>` rendering a query or a sub-query.
+ *
+ * This replaces two components that were the same grid written twice — and, counting
+ * `spark-query-list`'s streaming and paged branches, the `<bs-datatable>` element itself written
+ * three times. The duplication had already produced four user-visible bugs, each fixed on one
+ * side and not the other: `[indeterminate]` on null booleans, permission state surviving a failed
+ * reload, a swallowed fetch failure, and virtual-scroll sizing. `SparkGridRenderers` was
+ * extracted to stop that and could only take the stateless helpers with it; this takes the rest.
+ *
+ * ## What it deliberately does NOT own: streaming
+ *
+ * `spark-grid-renderers.ts` records why — a websocket dependency graph must not reach the bundle
+ * of every PO detail page, none of which stream. So rows can come from **either** side:
+ *
+ *  - unbound `data` — the grid fetches for itself, paging and sorting server-side;
+ *  - bound `data` — the grid renders what it is given and never fetches.
+ *
+ * `spark-query-list` keeps the socket and feeds its snapshot in. This is the line `bs-datatable`
+ * itself draws: `[data]` and `[fetch]` are mutually exclusive, and binding both makes `[fetch]`
+ * win silently.
+ *
+ * ## Reading its state
+ *
+ * `query`, `entityType`, `customActions`, `selection`, `canRead`, `canCreate` and `resultCount`
+ * are readable so a host can render chrome around the grid. Read them through a template
+ * reference variable — `<spark-query-grid #grid>` … `grid.query()` — not `viewChild`: hosts wrap
+ * grids in `@if`, where a `viewChild` is intermittently undefined.
+ */
+declare class SparkQueryGridComponent {
+    private readonly sparkService;
+    private readonly gridRenderers;
+    private readonly queryRefresh;
+    readonly lang: SparkLanguageService;
+    /** Query alias or id. */
+    queryId: _angular_core.InputSignal<string>;
+    /**
+     * The parent persistent object this query is scoped to, when it has one.
+     *
+     * Optional, because not every query is a detail of something: a page can host a grid that
+     * stands on its own — "my accounts", a dashboard list — and the server already treats an absent
+     * parent as "no parent" rather than as an error. Requiring these made that shape impossible to
+     * express: the component simply never loaded, with no request, no error and no log.
+     *
+     * Pass both or neither. One without the other is ignored, matching `SparkService.executeQuery`,
+     * which omits either param when it is falsy, and the execute endpoint, which resolves a parent
+     * only when both are present.
+     */
+    parentId: _angular_core.InputSignal<string>;
+    parentType: _angular_core.InputSignal<string>;
+    /**
+     * Rows supplied from outside. When bound, the grid renders these and runs no fetch.
+     *
+     * This is how streaming stays out of this component (see the class comment). `null` — the
+     * 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>;
+    /**
+     * Server-side search term, passed through to the query.
+     *
+     * An input rather than a box, so the host owns the control and the grid owns the request. A
+     * host with client-side rows filters them itself before binding `data`.
+     */
+    search: _angular_core.InputSignal<string>;
+    /**
+     * Change this to re-run the query. Any value works; only its identity matters.
+     *
+     * A declarative token rather than only a `reload()` method, because calling a method means
+     * holding a component handle, and hosts wrap this grid in `@if`, where a `viewChild` is
+     * intermittently undefined.
+     *
+     * This drives the CHEAP refresh (see {@link reload}). It deliberately does not feed the main
+     * effect: re-running `loadData` would re-resolve the query, the entity types, the permissions
+     * and the lookups, and reset the user's page and sort on every button press.
+     */
+    reloadToken: _angular_core.InputSignal<unknown>;
+    /**
+     * Paging and sorting. Two-way, so a host driving `data` can sort those rows by whatever the
+     * user actually clicked — the datatable writes the new sort back through here.
+     */
+    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[]>;
+    /** 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>;
+    customActionExecuted: _angular_core.OutputEmitterRef<{
+        action: CustomActionDefinition;
+    }>;
+    colors: typeof Color;
+    query: _angular_core.WritableSignal<SparkQuery | null>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
+    allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
+    lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
+    loading: _angular_core.WritableSignal<boolean>;
+    canRead: _angular_core.WritableSignal<boolean>;
+    canCreate: _angular_core.WritableSignal<boolean>;
+    resultCount: _angular_core.WritableSignal<number | null>;
+    customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
+    fetchFn: _angular_core.WritableSignal<BsDatatableFetch<PersistentObject> | null>;
+    /**
+     * Why the component renders its own failure instead of only reporting one.
+     *
+     * `SparkService` is a bare `firstValueFrom` passthrough with no interceptor, so every failure
+     * surfaces here and nowhere else. A host embedding this grid cannot surface what it never sees,
+     * and the default has to be visible with no host cooperation — hence a rendered alert, not just
+     * an output.
+     */
+    errorMessage: _angular_core.WritableSignal<string | null>;
+    /** '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[]>;
+    /**
+     * True when rows do not come from this component's own fetch.
+     *
+     * Either because the host bound `data`, or because the query streams — a streaming query's rows
+     * arrive over a socket and `/execute` is not a way to get them. The grid recognises the second
+     * case itself rather than waiting to be told, because it resolves the query before the host can
+     * see it: left to `data` alone, every streaming grid would fire one pointless fetch on mount,
+     * before the host had anything to bind.
+     */
+    hasExternalData: _angular_core.Signal<boolean>;
+    /** Whether an action's selection rule is satisfied right now. The server checks it again. */
+    isActionEnabled(action: CustomActionDefinition): boolean;
+    constructor();
+    /**
+     * Re-run the query, keeping the current page, sort and scroll position.
+     *
+     * Data-level on purpose: it re-seeds the fetch closure and nothing else. For a definition
+     * change — new columns, a renamed query — the inputs themselves must change; that is the
+     * expensive path. Inert when rows come from the host: there is nothing here to re-run.
+     */
+    reload(): void;
+    private onSearchChanged;
+    onCustomAction(action: CustomActionDefinition): Promise<void>;
+    private reportError;
+    /**
+     * A 404 is deliberately generic.
+     *
+     * `Endpoints/Queries/Get.cs` answers 404 with byte-identical bodies for "no such query" and
+     * "you may not see it", so existence is not disclosed (security audit M-3). The component
+     * therefore genuinely cannot tell them apart, and both "Not found" and "Access denied" would be
+     * a guess — one of them leaking, the other misleading.
+     */
+    private describe;
+    private loadData;
+    /**
+     * The query's entity type.
+     *
+     * The source-name fallback is not optional garnish: a `Database.*` query need not declare
+     * `entityType`, and the sub-query grid — which matched on the declared name alone — rendered
+     * those as an empty card with no columns, no rows and no error, while the identical query
+     * rendered correctly as a page. Both grids are this one now, so there is one answer.
+     */
+    private resolveEntityType;
+    private makeFetch;
+    private loadLookupReferenceOptions;
+    /**
+     * 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.
+     */
+    rendererValueFor(item: PersistentObject, attr: EntityAttributeDefinition): unknown;
+    getColumnRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;
+    getColumnRendererInputs(component: Type<any>, item: PersistentObject, attr: EntityAttributeDefinition): 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>;
+}
+
+/**
+ * A `<bs-card>` around a {@link SparkQueryGridComponent}: icon, caption, actions, grid.
+ *
+ * ## Chrome is overridden, not replaced
+ *
+ * Every header region has a default, and a host replaces only the ones it supplies. That is what
+ * lets this component serve the auto-rendered case: a sub-query is rendered once per entry in
+ * `EntityTypeDefinition.Queries` with nobody projecting into it, and it must look right with no
+ * host cooperation at all. A slot mechanism that only ever *replaced* chrome would leave that
+ * call site blank — which is why an earlier design had the query carry its own chrome from the
+ * server. Overriding a default needs no host; replacing one does.
+ *
+ * ## Two ways in, one set of templates
+ *
+ * Hand-written markup uses the structural directives and is found with `contentChildren`.
+ * The auto-rendered path cannot: `spark-po-detail` is created by the router, so in a default app
+ * there is no tag to project into. It therefore forwards `TemplateRef`s as inputs instead — a
+ * directive cannot cross a component boundary but its template can, and that forwarding is
+ * already the idiom in `spark-po-detail` (`extraActionsTemplate`, `extraContentTemplate`).
+ *
+ * Content wins over a forwarded input: the closer declaration is the more specific one.
+ */
+declare class SparkQueryCardComponent {
+    readonly lang: SparkLanguageService;
+    queryId: _angular_core.InputSignal<string>;
+    parentId: _angular_core.InputSignal<string>;
+    parentType: _angular_core.InputSignal<string>;
+    reloadToken: _angular_core.InputSignal<unknown>;
+    data: _angular_core.InputSignal<PersistentObject[] | null>;
+    search: _angular_core.InputSignal<string>;
+    /**
+     * Slots forwarded from a host that cannot project content — see the class comment. A card
+     * reached through hand-written markup should use the structural directives instead.
+     */
+    iconTemplate: _angular_core.InputSignal<TemplateRef<any> | null>;
+    captionTemplate: _angular_core.InputSignal<TemplateRef<any> | null>;
+    actionsTemplate: _angular_core.InputSignal<TemplateRef<any> | null>;
+    error: _angular_core.OutputEmitterRef<HttpErrorResponse>;
+    rowClicked: _angular_core.OutputEmitterRef<PersistentObject>;
+    customActionExecuted: _angular_core.OutputEmitterRef<{
+        action: CustomActionDefinition;
+    }>;
+    colors: typeof Color;
+    private readonly iconSlots;
+    private readonly captionSlots;
+    private readonly actionSlots;
+    /**
+     * The grid, read only to surface its state — the query, the actions, the selection — to this
+     * component's own header.
+     *
+     * Optional rather than `required` on purpose. The header renders ABOVE the grid in this
+     * template, so on the first change-detection pass the view query has not resolved yet and
+     * `viewChild.required()` would throw where a plain one returns `undefined`. Everything below
+     * therefore reads it defensively; the signal updates once the view initialises and the header
+     * re-renders with the real query.
+     *
+     * A host reads grid state through a template reference variable instead, because a host may put
+     * the grid behind an `@if`, where a view query genuinely is intermittently undefined.
+     */
+    protected readonly grid: _angular_core.Signal<SparkQueryGridComponent | undefined>;
+    protected readonly query: _angular_core.Signal<_mintplayer_ng_spark_models.SparkQuery | null>;
+    protected readonly iconTpl: _angular_core.Signal<TemplateRef<any> | null>;
+    protected readonly captionTpl: _angular_core.Signal<TemplateRef<any> | null>;
+    protected readonly actionsTpl: _angular_core.Signal<TemplateRef<any> | null>;
+    /** 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[]>;
+    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>;
+}
+
+/**
+ * One cell of a Spark table, wherever that table is.
+ *
+ * ## Why this exists
+ *
+ * The cell markup was written out three times: twice in the query grids (since merged into
+ * {@link SparkQueryGridComponent}) and once more in the AsDetail table on the PO detail page. The
+ * third copy was never counted, and it had already drifted — a `boolean` column rendered the text
+ * `"true"` there while the grid rendered a checkbox, a `color` rendered its hex string rather than
+ * a swatch, and a custom renderer was dispatched by a second, hand-copied lookup.
+ *
+ * ## What it does and does not own
+ *
+ * It owns **presentation**: which control a `dataType` becomes, and dispatching a declared custom
+ * renderer. It does not own **value resolution**, and deliberately so — the two callers read from
+ * genuinely different row models. A query row is a `PersistentObject` with an attribute list and
+ * an id; an AsDetail row is a plain dictionary of embedded values with neither. Trying to unify
+ * that would put a second row-access path inside this component and buy nothing.
+ *
+ * So the caller resolves the value with whichever pipe fits its row model, and passes the result.
+ *
+ * ## The two links are not the same link, and only one is here
+ *
+ * `link` is for a cell whose own value points at another entity — an AsDetail reference column.
+ * The query grid's first-column link is a different rule (it points at the row's own detail page,
+ * gated on `Read`), and it stays in the grid, wrapping this component. Passing both would nest
+ * anchors, which is invalid HTML; the grid therefore leaves `link` unset.
+ */
+declare class SparkGridCellComponent {
+    private readonly renderers;
+    /** The column being rendered. Its `dataType` and `renderer` decide everything below. */
+    column: _angular_core.InputSignal<EntityAttributeDefinition>;
+    /**
+     * 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.
+     */
+    display: _angular_core.InputSignal<unknown>;
+    /**
+     * The value handed to a declared custom renderer.
+     *
+     * Separate from {@link display} because they are not the same thing: a renderer receives the
+     * underlying value — for AsDetail, the nested object itself — while `display` has already been
+     * flattened to something printable.
+     */
+    rendererValue: _angular_core.InputSignal<unknown>;
+    /** The row, passed through to a custom renderer as `item`. */
+    item: _angular_core.InputSignal<unknown>;
+    /**
+     * Pre-resolved chips for a reference-array column, or empty when the column is not one.
+     *
+     * Resolved by the caller because the label source differs: a query row carries a per-id
+     * breadcrumb map, while an AsDetail row's `__sparkBreadcrumbs` is keyed by column name only and
+     * so cannot label the members of an array. Rather than render a row of raw ids, an AsDetail
+     * caller passes nothing and the cell falls through to text.
+     */
+    chips: _angular_core.InputSignal<ReferenceChip[]>;
+    /** Route for a cell whose value references another entity. See the class comment. */
+    link: _angular_core.InputSignal<unknown[] | null>;
+    protected readonly rendererComponent: _angular_core.Signal<_angular_core.Type<any> | null>;
+    protected readonly rendererInputs: _angular_core.Signal<Record<string, any>>;
+    /** Null and undefined are distinct from `false` here — see the template. */
+    protected readonly isUnsetBoolean: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkGridCellComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkGridCellComponent, "spark-grid-cell", never, { "column": { "alias": "column"; "required": true; "isSignal": true; }; "display": { "alias": "display"; "required": false; "isSignal": true; }; "rendererValue": { "alias": "rendererValue"; "required": false; "isSignal": true; }; "item": { "alias": "item"; "required": false; "isSignal": true; }; "chips": { "alias": "chips"; "required": false; "isSignal": true; }; "link": { "alias": "link"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { SPARK_GRID_PAGE_SIZES, SparkGridCellComponent, SparkGridRenderers, SparkQueryActionsContext, SparkQueryActionsDirective, SparkQueryCaptionContext, SparkQueryCaptionDirective, SparkQueryCardComponent, SparkQueryGridComponent, SparkQueryIconDirective, SparkQuerySlotContext, initialGridSettings, isVirtualScrollingQuery, slotFor, visibleGridAttributes };

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

@@ -335,7 +335,9 @@ type StreamingMessage = StreamingSnapshotMessage | StreamingPatchMessage | Strea
 
 /**
  * Resolves an `EntityType` by its CLR type name (e.g. `"HR.Entities.Address"`).
- * Callers typically close over `sparkService.getEntityTypes()`'s cached list.
+ * Callers typically close over a list they already hold. `getEntityTypes()` is NOT cached --
+ * it issues a request per call -- so resolve against a list you fetched once rather than
+ * calling it inside the resolver.
  */
 type EntityTypeResolver = (clrTypeName: string) => EntityType | undefined;
 /**
@@ -348,6 +350,28 @@ type EntityTypeResolver = (clrTypeName: string) => EntityType | undefined;
  * back to the flat dict the form components already handle.
  */
 declare function nestedPoToDict(po: PersistentObject | null | undefined): Record<string, any>;
+/**
+ * Reserved key under which a flattened nested object keeps the breadcrumb the SERVER resolved for
+ * that object itself (as opposed to {@link AS_DETAIL_BREADCRUMBS_KEY}, which keys the breadcrumbs
+ * of its reference attributes by attribute name).
+ *
+ * This exists because a breadcrumb template can name a property the model does not carry. HR's
+ * `Address` declares `[Breadcrumb, IgnoreProperty] string Crumb`, and `Address.json` renders it as
+ * `"{Crumb}"` — the server resolves that by reflecting over the CLR property, which no client can
+ * do, because `[IgnoreProperty]` is exactly the instruction to keep it out of the model. Flattening
+ * used to discard the resolved string, leaving the form to substitute `{Crumb}` against a dict that
+ * can never contain it.
+ */
+declare const AS_DETAIL_SELF_BREADCRUMB_KEY = "__sparkBreadcrumb";
+/**
+ * The breadcrumb the server resolved for a flattened object, or null when it resolved to nothing.
+ *
+ * `EntityMapper` never emits an empty breadcrumb: when the template renders blank it substitutes
+ * the CLR type name, so an unset `Address` arrives as the literal string `"Address"`
+ * (EntityMapper.cs:209-211). That is a placeholder, not data, and rendering it would be worse than
+ * rendering nothing — it reads as a real value. `typeName` lets a caller filter it back out.
+ */
+declare function selfBreadcrumb(row: Record<string, any> | null | undefined, typeName?: string): string | null;
 /**
  * Reserved key under which {@link nestedPoToDisplayRow} stashes the server-resolved breadcrumb of
  * each reference attribute (keyed by attribute name). Lets an AsDetail reference cell render the
@@ -375,5 +399,52 @@ declare function nestedPoToDisplayRow(po: PersistentObject | null | undefined):
  */
 declare function dictToNestedPo(dict: Record<string, any> | null | undefined, entityType: EntityType, resolve: EntityTypeResolver): PersistentObject;
 
-export { AS_DETAIL_BREADCRUMBS_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, currentLanguage, dictToNestedPo, hasShowedOnFlag, nestedPoToDict, nestedPoToDisplayRow, resolveTranslation };
-export type { AttributeGroup, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RetryActionPayload, RetryActionResult, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };
+/**
+ * The custom actions a query should offer, from the entity type's full set.
+ *
+ * `showedOn` must include the query side. The accepted values are `"detail"`, `"query"`
+ * and `"both"` — as the server model and the custom-actions guide have always
+ * documented. Both grids previously tested for `"list"`, a value nothing emits, so an
+ * action authored per the documentation rendered nowhere at all.
+ *
+ * ⚠️ This narrows what is DISPLAYED. It is NOT an authorization boundary: the grant
+ * is, and it is enforced independently in `ExecuteCustomAction` regardless of which
+ * query the caller clicked from — a caller can always POST directly.
+ */
+declare function filterQueryActions(actions: CustomActionDefinition[]): CustomActionDefinition[];
+
+/**
+ * Parses a custom action's `selectionRule` — a cardinality expression over the number
+ * of selected rows — into a predicate.
+ *
+ * A port of the server's `SelectionRuleParser`, and the two MUST agree: they are tested
+ * against one shared fixture (`selection-rule.fixture.json`) for exactly this reason.
+ * Vidyano, where this grammar comes from, has the same algorithm in C# and JavaScript and
+ * the two have already drifted — one throws on a non-numeric operand where the other
+ * silently permits everything.
+ *
+ * Grammar: `X` is the count placeholder, whitespace is insignificant, terms split on `X`
+ * are AND-combined (`1<X<5` is a range), operators are `<= >= < > != =` matched in that
+ * order so `>=` is never read as `>`, and a number-first term is mirrored (`0<X` is `>0`).
+ *
+ * Client-side this only drives whether a button is disabled. The server enforces the same
+ * rule independently — and neither is an authorization boundary: the action's grant is.
+ */
+declare function parseSelectionRule(rule?: string | null): (count: number) => boolean;
+
+type SparkSelectionMode = 'none' | 'single' | 'multiple';
+/**
+ * The selection mode a grid needs in order to satisfy the actions offered on it.
+ *
+ * Derived rather than configured, so a grid gains a checkbox column exactly when an
+ * action needs one and is otherwise pixel-identical to a grid with no selection at all.
+ * Vidyano's query grid does the same thing — it renders the checkbox column only if some
+ * action is selection-gated.
+ *
+ * `'single'` when every gated action is satisfied by one row and refused by two; anything
+ * else that cares about the count gets `'multiple'`.
+ */
+declare function selectionModeFor(actions: CustomActionDefinition[]): SparkSelectionMode;
+
+export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, currentLanguage, dictToNestedPo, filterQueryActions, hasShowedOnFlag, nestedPoToDict, nestedPoToDisplayRow, parseSelectionRule, resolveTranslation, selectionModeFor, selfBreadcrumb };
+export type { AttributeGroup, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RetryActionPayload, RetryActionResult, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };