@mintplayer/ng-spark 22.1.0 → 22.3.0

package/types/mintplayer-ng-spark-client-operations.d.ts

@@ -157,14 +157,40 @@ declare class SparkToastContainerComponent {
 }
 
 /**
- * Registers the built-in client-operation handlers. Currently registers `notify`;
- * additional types (`navigate`, `refreshQuery`, `refreshAttribute`, `disableAction`)
- * land in subsequent commits. Apps add this once in their bootstrap providers.
+ * Registers the built-in client-operation handlers: `notify` and `refreshQuery`.
+ * Apps add this once in their bootstrap providers.
+ *
+ * Unregistered operation types are dropped SILENTLY by the dispatcher, which is why
+ * `refreshQuery` did nothing at all for as long as it went unhandled — the server emitted
+ * it, nothing listened, and no error said so. `disableAction` is in that state today: it is
+ * registered below purely to log, so the gap is visible rather than invisible.
  *
  * To register custom operation types alongside the built-ins, add additional
  * `multi: true` providers using <see cref="SPARK_CLIENT_OPERATION_HANDLERS" />.
  */
 declare function provideSparkClientOperations(): EnvironmentProviders;
 
-export { NotificationKind, SPARK_CLIENT_OPERATION_HANDLERS, SparkClientOperationDispatcher, SparkNotificationService, SparkToastContainerComponent, provideSparkClientOperations };
+/**
+ * Carries a server-issued `refreshQuery` to whichever grids are showing that query.
+ *
+ * A broadcast signal rather than a registry of component handles: grids come and go behind
+ * `@if` and lazy routes, and nothing else in ng-spark holds a component reference. A grid
+ * reads {@link tokenFor} in an effect and re-fetches when it changes, which is the same
+ * declarative shape as the `reloadToken` input a host would use.
+ *
+ * Until this existed the server could emit the operation and the dispatcher dropped it: only
+ * `notify` was registered, and unknown types are ignored silently — so `refreshOnCompleted`
+ * on the server had no effect on any grid the action did not happen to be hosted in.
+ */
+declare class SparkQueryRefreshService {
+    private readonly tokens;
+    /** Bumped every time the server asks for this query to refresh. */
+    tokenFor(queryId: string | undefined): number;
+    /** Ask every grid showing `queryId` to re-fetch. Matched on id AND alias, since a grid may hold either. */
+    request(queryId: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryRefreshService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkQueryRefreshService>;
+}
+
+export { NotificationKind, SPARK_CLIENT_OPERATION_HANDLERS, SparkClientOperationDispatcher, SparkNotificationService, SparkQueryRefreshService, SparkToastContainerComponent, provideSparkClientOperations };
 export type { ClientOperation, ClientOperationEnvelope, ClientOperationHandler, ClientOperationHandlerRegistration, DisableActionOperation, DisableTarget, NavigateOperation, NotifyOperation, RefreshAttributeOperation, RefreshQueryOperation, RetryOperation, SparkToast };

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

@@ -0,0 +1,63 @@
+import { DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
+import { SparkQuery, EntityType, EntityAttributeDefinition, PersistentObject, LookupReference } from '@mintplayer/ng-spark/models';
+import * as i0 from '@angular/core';
+import { Type } from '@angular/core';
+
+/** 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;
+
+/**
+ * The parts of a Spark grid that both grid components need and that were, until this existed,
+ * written out twice.
+ *
+ * `spark-query-list` and `spark-sub-query` had byte-identical copies of the renderer lookup, the
+ * renderer input construction and the lookup-reference loading — around 120 lines between them.
+ * That duplication is not a tidiness complaint: it is what produced the 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, because nothing made the two files move together.
+ *
+ * Kept deliberately small and stateless. The two components differ in real ways — one is
+ * route-coupled and carries streaming, search and a websocket dependency graph — so merging them
+ * into a single component would drag all of that into every detail page's bundle. Shared logic
+ * belongs here; shared *state* does not.
+ */
+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>;
+    /**
+     * 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: i0.ɵɵFactoryDeclaration<SparkGridRenderers, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkGridRenderers>;
+}
+
+export { SPARK_GRID_PAGE_SIZES, SparkGridRenderers, initialGridSettings, isVirtualScrollingQuery, visibleGridAttributes };

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

@@ -290,6 +290,13 @@ interface RetryActionResult {
 }
 
 interface EntityPermissions {
+    /**
+     * Whether the caller may list this type. Independently grantable from `canRead` — `Query/Person`
+     * alone lists rows while refusing a by-id load — and reported since preview.60. The combined
+     * `QueryRead` right bundles the two invisibly, which is why this was the one action introspection
+     * never mentioned.
+     */
+    canQuery: boolean;
     canRead: boolean;
     canCreate: boolean;
     canEdit: boolean;
@@ -368,5 +375,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, ELookupDisplayType, EReferenceDisplayType, ShowedOn, currentLanguage, dictToNestedPo, filterQueryActions, hasShowedOnFlag, nestedPoToDict, nestedPoToDisplayRow, parseSelectionRule, resolveTranslation, selectionModeFor };
+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 };

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

@@ -2,13 +2,16 @@ 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 * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
 import { PersistentObject, EntityType, CustomActionDefinition, LookupReference, EntityAttributeDefinition, AttributeTab, AttributeGroup, SparkQuery } from '@mintplayer/ng-spark/models';
+import { HttpErrorResponse } from '@angular/common/http';
 import { DatatableSettings, BsDatatableFetch } from '@mintplayer/ng-bootstrap/datatable';
 
 declare class SparkPoDetailComponent {
     private readonly route;
     private readonly router;
     private readonly sparkService;
+    private readonly queryRefresh;
     protected readonly lang: SparkLanguageService;
     private readonly rendererRegistry;
     showCustomActions: _angular_core.InputSignal<boolean>;
@@ -61,29 +64,135 @@ declare class SparkPoDetailComponent {
 
 declare class SparkSubQueryComponent {
     private readonly sparkService;
-    private readonly rendererRegistry;
+    private readonly gridRenderers;
+    readonly lang: SparkLanguageService;
     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. Leaving these required 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>;
+    /**
+     * 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. Nothing else in ng-spark
+     * uses `viewChild` either — the house idiom is to re-seed a signal.
+     *
+     * 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>;
+    /**
+     * Render without the surrounding card, for a host that owns its own chrome — a tab
+     * body, a modal, a dashboard tile.
+     *
+     * This is the escape hatch for a genuinely chromeless embed. It only serves a host
+     * that instantiated this component by hand — where the component is auto-rendered
+     * from `EntityTypeDefinition.Queries` there is no host to pass it.
+     */
+    showCard: _angular_core.InputSignal<boolean>;
+    /**
+     * Replace the header for one hand-instantiated usage.
+     *
+     * A `TemplateRef` rather than `<ng-content>` deliberately: it matches
+     * `spark-po-detail`'s `extraActionsTemplate`/`extraContentTemplate`, and unlike
+     * projection it can be forwarded by a host that is itself several layers up.
+     *
+     * Precedence is headerTemplate -> caption + query actions.
+     */
+    headerTemplate: _angular_core.InputSignal<TemplateRef<{
+        $implicit: SparkQuery;
+    }> | null>;
+    colors: typeof Color;
     query: _angular_core.WritableSignal<SparkQuery | null>;
     entityType: _angular_core.WritableSignal<EntityType | null>;
     allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
-    resultCount: _angular_core.WritableSignal<number | 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.
+     *
+     * A 404 is deliberately vague. `Endpoints/Queries/Get.cs` answers 404 for BOTH
+     * "no such query" and "you may not see it", with byte-identical bodies, so that
+     * existence is not disclosed (security audit M-3). This component therefore
+     * genuinely cannot tell the two apart, and any message claiming otherwise would
+     * either leak or mislead.
+     */
+    errorMessage: _angular_core.WritableSignal<string | null>;
+    /**
+     * Actions the query declares, rendered in this component's own header.
+     *
+     * This is what makes a query's chrome work with no host: a sub-query is rendered
+     * automatically from `EntityTypeDefinition.Queries`, so there is nobody to project
+     * a toolbar in. The query says what belongs in its header, and it follows the query
+     * wherever it is rendered.
+     */
+    customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
+    /** Emitted whenever a load or a page fetch fails, for a host in bespoke chrome. */
+    error: _angular_core.OutputEmitterRef<HttpErrorResponse>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
     loading: _angular_core.WritableSignal<boolean>;
     canRead: _angular_core.WritableSignal<boolean>;
     settings: _angular_core.WritableSignal<DatatableSettings>;
     fetchFn: _angular_core.WritableSignal<BsDatatableFetch<PersistentObject> | null>;
+    /**
+     * Rows the user has ticked. Lives here rather than in the datatable so the action bar can
+     * read it, and MUST be cleared whenever the source changes — otherwise route A's selection
+     * is POSTed as ids of route B's type.
+     */
+    selection: _angular_core.WritableSignal<PersistentObject[]>;
+    private readonly queryRefresh;
+    /** 'none' unless an action is selection-gated, so unaffected grids gain no checkbox column. */
+    selectionMode: _angular_core.Signal<_mintplayer_ng_spark_models.SparkSelectionMode>;
+    /** Whether an action's selection rule is satisfied right now. The server checks it again. */
+    isActionEnabled(action: CustomActionDefinition): boolean;
     isVirtualScrolling: _angular_core.Signal<boolean>;
     visibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     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, mirroring
+     * `SparkQueryListComponent.reload()`. Use it after something mutates server-side
+     * state the query reads from. For a definition change — new columns, a renamed
+     * query — the inputs themselves must change; that is the expensive path.
+     */
+    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 (audit M-3). The
+     * component therefore cannot tell them apart, and both "Not found" and "Access
+     * denied" would be a guess — one of them leaking, the other misleading.
+     */
+    private describe;
+    reload(): void;
     private loadData;
     private makeFetch;
     private loadLookupReferenceOptions;
     getColumnRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;
     getColumnRendererInputs(component: Type<any>, item: PersistentObject, attr: EntityAttributeDefinition): Record<string, any>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkSubQueryComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkSubQueryComponent, "spark-sub-query", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": true; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkSubQueryComponent, "spark-sub-query", 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; }; "showCard": { "alias": "showCard"; "required": false; "isSignal": true; }; "headerTemplate": { "alias": "headerTemplate"; "required": false; "isSignal": true; }; }, { "error": "error"; }, never, never, true, never>;
 }
 
 export { SparkPoDetailComponent, SparkSubQueryComponent };

package/types/mintplayer-ng-spark-query-list.d.ts

@@ -1,9 +1,10 @@
+import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
+import { PersistentObject, CustomActionDefinition, SparkQuery, EntityType, LookupReference, EntityAttributeDefinition } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
 import { TemplateRef, Type } from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
 import { BsDatatableFetch, DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
 import { SparkLanguageService } from '@mintplayer/ng-spark/services';
-import { PersistentObject, CustomActionDefinition, SparkQuery, EntityType, LookupReference, EntityAttributeDefinition } from '@mintplayer/ng-spark/models';
 
 declare class SparkQueryListComponent {
     private readonly route;
@@ -11,7 +12,7 @@ declare class SparkQueryListComponent {
     private readonly sparkService;
     private readonly streamingService;
     protected readonly lang: SparkLanguageService;
-    private readonly rendererRegistry;
+    private readonly gridRenderers;
     private readonly destroyRef;
     extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void> | null>;
     showCustomActions: _angular_core.InputSignal<boolean>;
@@ -39,6 +40,12 @@ declare class SparkQueryListComponent {
     settings: _angular_core.WritableSignal<DatatableSettings>;
     constructor();
     private onParamsChange;
+    /**
+     * A load failure has to render, not just be swallowed: a denied query answers 404
+     * (audit M-3, so existence is not leaked), which is indistinguishable from a missing
+     * one -- hence a deliberately generic message rather than a guess at which it was.
+     */
+    private reportLoadFailure;
     onCustomAction(action: CustomActionDefinition): Promise<void>;
     private resolveEntityTypeForQuery;
     private extractSourceName;
@@ -49,10 +56,36 @@ declare class SparkQueryListComponent {
      * refetches with the current search term.
      */
     private makeFetch;
-    /** Force a refetch (e.g. after a custom action) without changing page/sort. */
-    private refresh;
+    /**
+     * Force a refetch (e.g. after a custom action) without changing page/sort.
+     *
+     * Public so a host can drive it, and named to match
+     * `SparkSubQueryComponent.reload()` — the two grids had drifted into having the
+     * same mechanism under different names, one of them unreachable.
+     */
+    reload(): void;
     onSearchChange(): void;
     clearSearch(): void;
+    /**
+     * Whether the first column links to a detail page.
+     *
+     * Declared by the query, because the framework cannot derive it: `Database.*` rows
+     * are always real documents, but a `Custom.*` query may return loadable documents
+     * (Fleet's Stolen_Cars) or rows fabricated in memory (StreamItems). Absent means
+     * navigable -- defaulting Custom.* to false would strip the working links off every
+     * custom query that does return documents.
+     */
+    /**
+     * Rows the user has ticked. Lives here rather than in the datatable so the action bar can
+     * read it, and MUST be cleared whenever the source changes — otherwise route A's selection
+     * is POSTed as ids of route B's type.
+     */
+    selection: _angular_core.WritableSignal<PersistentObject[]>;
+    private readonly queryRefresh;
+    /** 'none' unless an action is selection-gated, so unaffected grids gain no checkbox column. */
+    selectionMode: _angular_core.Signal<_mintplayer_ng_spark_models.SparkSelectionMode>;
+    /** Whether an action's selection rule is satisfied right now. The server checks it again. */
+    isActionEnabled(action: CustomActionDefinition): boolean;
     isVirtualScrolling: _angular_core.Signal<boolean>;
     visibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     getColumnRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;