@mintplayer/ng-spark 22.11.0 → 22.13.0

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

@@ -26,6 +26,15 @@ interface RefreshAttributeOperation {
     id: string;
     attributeName: string;
     value?: unknown;
+    /**
+     * Nested rows of an `AsDetail` attribute. A loaded AsDetail attribute carries its rows in
+     * `object` / `objects` and leaves `value` null, so a patch limited to `value` could never
+     * refresh a detail grid -- it always sent null, and a null over a null repaints nothing.
+     *
+     * An empty `objects` array means the grid is now empty, and is distinct from omitting it.
+     */
+    object?: unknown;
+    objects?: unknown[];
 }
 interface RefreshQueryOperation {
     type: 'refreshQuery';
@@ -157,13 +166,21 @@ declare class SparkToastContainerComponent {
 }
 
 /**
- * Registers the built-in client-operation handlers: `notify` and `refreshQuery`.
- * Apps add this once in their bootstrap providers.
+ * Registers the built-in client-operation handlers: `notify`, `refreshQuery`,
+ * `refreshAttribute` and `navigate`. 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.
+ * it, nothing listened, and no error said so.
+ *
+ * That happened twice more before anyone noticed. `refreshAttribute` and `navigate` were both
+ * declared wire types with no handler anywhere in the repository: every
+ * `IClientAccessor.RefreshAttribute` and `Navigate` call in every Spark application was
+ * computed, serialised, sent and discarded. Both are registered below. The remaining gap is
+ * `disableAction`, registered purely to log so that it stays visible rather than invisible.
+ *
+ * The lesson worth keeping: a wire type in `operations.ts` is not a feature. Adding one without
+ * a handler here produces a server API that appears to work and does nothing.
  *
  * To register custom operation types alongside the built-ins, add additional
  * `multi: true` providers using <see cref="SPARK_CLIENT_OPERATION_HANDLERS" />.
@@ -201,5 +218,68 @@ declare class SparkQueryRefreshService {
     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 };
+/**
+ * Carries a server-issued `refreshAttribute` to whichever detail page is showing that object.
+ *
+ * The same broadcast shape as {@link SparkQueryRefreshService}, and for the same reason: detail
+ * pages come and go behind `@if` and lazy routes, and nothing in ng-spark holds a component
+ * reference. A page reads {@link tokenFor} in an effect and applies {@link patchesFor} when it
+ * changes.
+ *
+ * Until this existed the operation was declared on the wire and handled by nobody: the server
+ * computed the new values, serialised them, sent them, and the dispatcher dropped them silently
+ * because unknown types are ignored. `IClientAccessor.RefreshAttribute` was inert in every Spark
+ * application. It is what made the Coverage home page's Resync button look dead — it recomputed
+ * the account and repository counts correctly on every click and none of them ever arrived.
+ *
+ * The operation carries the new value, so this is a patch and not a re-fetch: no round trip, and
+ * no dependence on an index that may still be stale from the write that triggered it.
+ */
+/**
+ * The parts of an attribute a server patch may carry.
+ *
+ * Three fields rather than one value because a loaded attribute does not keep every shape in
+ * `value`: an `AsDetail` attribute puts its nested rows in `object` / `objects` and leaves
+ * `value` null. A patch limited to `value` was therefore incapable of refreshing a detail grid,
+ * and did so silently -- see {@link SparkAttributeRefreshService}.
+ *
+ * Only the keys the server sent are present, and each is applied on its own. An `objects: []`
+ * means the grid is now empty, which is why emptiness has to be distinguishable from absence.
+ */
+interface SparkAttributePatch {
+    value?: unknown;
+    object?: unknown;
+    objects?: unknown[];
+}
+declare class SparkAttributeRefreshService {
+    private readonly tokens;
+    private readonly patches;
+    /**
+     * Objects are keyed by type AND id: the same id can exist under two types, and a detail page
+     * only ever wants the attributes meant for the object it is showing.
+     */
+    private static keyFor;
+    /** Bumped every time the server patches an attribute of this object. */
+    tokenFor(objectTypeId: string | undefined | null, id: string | undefined | null): number;
+    /**
+     * The newest value the server sent for each patched attribute of this object.
+     *
+     * Cumulative rather than drained on read: a detail page that mounts after the operation arrived
+     * still sees the value, and two pages showing the same object both get it. Values are overwritten
+     * by later patches, so this holds one entry per attribute, not a history.
+     */
+    patchesFor(objectTypeId: string | undefined | null, id: string | undefined | null): Record<string, SparkAttributePatch>;
+    /**
+     * Record a new value for one attribute and wake whoever is showing the object.
+     *
+     * Callers patching several attributes for one user action should do so in one synchronous run:
+     * the signals coalesce within a tick into a single effect run, and patches split across an await
+     * become one run each.
+     */
+    request(objectTypeId: string, id: string, attributeName: string, patch: SparkAttributePatch): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkAttributeRefreshService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkAttributeRefreshService>;
+}
+
+export { NotificationKind, SPARK_CLIENT_OPERATION_HANDLERS, SparkAttributeRefreshService, SparkClientOperationDispatcher, SparkNotificationService, SparkQueryRefreshService, SparkToastContainerComponent, provideSparkClientOperations };
+export type { ClientOperation, ClientOperationEnvelope, ClientOperationHandler, ClientOperationHandlerRegistration, DisableActionOperation, DisableTarget, NavigateOperation, NotifyOperation, RefreshAttributeOperation, RefreshQueryOperation, RetryOperation, SparkAttributePatch, SparkToast };

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

@@ -308,6 +308,19 @@ declare class SparkQueryGridComponent {
     canCreate: _angular_core.WritableSignal<boolean>;
     resultCount: _angular_core.WritableSignal<number | null>;
     customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
+    /** Names the server withheld for this RESULT; see QueryResult.disabledActions. */
+    private readonly disabledActions;
+    /**
+     * The actions actually offered for this result.
+     *
+     * The catalogue at `/spark/actions/{objectTypeId}` is per TYPE and is never told what an
+     * execution returned, so an action that applies to only some results cannot be filtered there.
+     * A custom query withholds what does not apply via `CustomQueryArgs.DisableActions(...)`, and
+     * the answer arrives on the result.
+     *
+     * An affordance, not a permission -- the action handler still refuses on its own terms.
+     */
+    visibleCustomActions: _angular_core.Signal<CustomActionDefinition[]>;
     fetchFn: _angular_core.WritableSignal<BsDatatableFetch<QueryResultItem> | null>;
     /**
      * Why the component renders its own failure instead of only reporting one.
@@ -534,6 +547,16 @@ declare class SparkGridCellComponent {
     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>;
+    /**
+     * {@link display} when it really is a `Date`, and `null` otherwise.
+     *
+     * Angular's `DatePipe` does not degrade on a non-date: it **throws**
+     * `NG02100: InvalidPipeArgument`, which would take down the whole cell. Both cell pipes
+     * deliberately fall back to the raw text for an unparseable date rather than hiding the stored
+     * value, so that text reaches this component and must not be piped. A template cannot express
+     * `instanceof`, hence the computed.
+     */
+    protected readonly dateValue: _angular_core.Signal<Date | null>;
     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>;
 }

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

@@ -56,6 +56,19 @@ interface PersistentObject {
     attributes: PersistentObjectAttribute[];
     /** Per-row edit/delete affordances; undefined = fall back to type-level permissions. */
     can?: PersistentObjectPermissions;
+    /**
+     * Custom actions withheld for THIS object, by name. Absent or empty means every action the
+     * caller has the right to is offered.
+     *
+     * The action catalogue at `/spark/actions/{objectTypeId}` is per TYPE -- it is never told which
+     * row is open -- so an action that applies to only some rows cannot be filtered there. The
+     * entity actions hook decides while it has the entity in hand, and the answer arrives here.
+     *
+     * An affordance, not a permission: the action endpoint is still reachable and its handler still
+     * refuses on its own terms. What this prevents is offering a destructive action where it cannot
+     * apply.
+     */
+    disabledActions?: string[];
 }
 
 interface PersistentObjectAttribute {
@@ -199,6 +212,14 @@ interface EntityType {
      * query. Types are data from the wire, not a promise about it.
      */
     clrType?: string;
+    /**
+     * Whether this caller may OPEN one of these, as opposed to list them.
+     *
+     * The catalogue is gated on Query, so its presence here means "you may list this type" and says
+     * nothing about opening one. A reference must not render as a link when this is false: it used
+     * to, and the click refused on arrival.
+     */
+    canRead?: boolean;
     alias?: string;
     /**
      * Breadcrumb template: literal text plus `{AttributeName}` placeholders. A scalar placeholder
@@ -256,6 +277,17 @@ interface QueryResult {
     skip: number;
     take: number;
     typeHints?: Record<string, string>;
+    /**
+     * Custom actions withheld for THIS result, by name. Absent or empty means every action the
+     * caller has the right to is offered.
+     *
+     * The mirror of `PersistentObject.disabledActions`, set server-side via
+     * `CustomQueryArgs.DisableActions(...)`. The action catalogue is per type and is never told what
+     * an execution returned, so this is where a per-result answer travels.
+     *
+     * An affordance, not a permission -- the action handler still refuses on its own terms.
+     */
+    disabledActions?: string[];
 }
 /**
  * The subset of column metadata a cell needs in order to render.

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

@@ -96,8 +96,44 @@ declare class AsDetailColumnsPipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<AsDetailColumnsPipe, "asDetailColumns", true>;
 }
 
+/** What a cell can resolve to: the column's own type, or `null` when it has no value. */
+type AsDetailCellValue = string | number | boolean | Date | null;
+/**
+ * The value of one cell in an `AsDetail` table, **typed by the column's `dataType`** rather than
+ * flattened to a string.
+ *
+ * <p>
+ * This used to end in `return String(value)` for everything, and declare `: string`. That is fine
+ * for a cell which is only interpolated, and wrong for one whose consumer inspects it —
+ * `spark-grid-cell` branches on the column type and binds `[checked]="display() === true"` and
+ * `[indeterminate]="display() == null"` for a boolean, so it needs the value and not a rendering
+ * of it.
+ * </p>
+ * <p>
+ * The visible symptom was a detail page showing unticked checkboxes for rows whose edit form showed
+ * them ticked — the edit form reads `attribute.objects` directly, so it never went through here. All
+ * three states of a `bool?` were affected, and one of them silently:
+ * </p>
+ * <ul>
+ *   <li><b>true</b> — `'true' === true` is false, so it rendered <b>unchecked</b>;</li>
+ *   <li><b>null</b> — became `''`, and `'' == null` is false, so it rendered unchecked <b>and
+ *       determinate</b>, i.e. claiming to be false;</li>
+ *   <li><b>false</b> — `'false'` is not `=== true`, so it rendered correctly <b>by accident</b>.</li>
+ * </ul>
+ * <p>
+ * Types that stay strings do so deliberately, not by omission. `color`, `image` and `url` are bound
+ * into a style, an `src` and an `href`, so a string is what they need. `Reference` and `AsDetail`
+ * resolve to a breadcrumb, which is a label rather than a value.
+ * </p>
+ * <p>
+ * `date` and `datetime` return a real `Date`. They arrive as ISO strings, and the cell used to
+ * print that string verbatim — `2026-09-07T13:25:57.3119825Z` in a table column. Returning the
+ * parsed value lets `spark-grid-cell` format it in one place for both grids; an unparseable value
+ * falls back to its text, because showing what is there beats showing `Invalid Date`.
+ * </p>
+ */
 declare class AsDetailCellValuePipe implements PipeTransform {
-    transform(row: Record<string, any>, parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, QueryResultItem[]>>): string;
+    transform(row: Record<string, any>, parentAttr: EntityAttributeDefinition, col: EntityAttributeDefinition, asDetailRefOptions: Record<string, Record<string, QueryResultItem[]>>): AsDetailCellValue;
     static ɵfac: i0.ɵɵFactoryDeclaration<AsDetailCellValuePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<AsDetailCellValuePipe, "asDetailCellValue", true>;
 }
@@ -200,4 +236,4 @@ declare class QueryReferenceChipsPipe implements PipeTransform {
 }
 
 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 };
+export type { AsDetailCellValue, ReferenceChip };

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

@@ -9,6 +9,7 @@ declare class SparkPoDetailComponent {
     private readonly router;
     private readonly sparkService;
     private readonly queryRefresh;
+    private readonly attributeRefresh;
     protected readonly lang: SparkLanguageService;
     private readonly rendererRegistry;
     showCustomActions: _angular_core.InputSignal<boolean>;
@@ -51,7 +52,29 @@ declare class SparkPoDetailComponent {
     canEdit: _angular_core.WritableSignal<boolean>;
     canDelete: _angular_core.WritableSignal<boolean>;
     customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
+    /**
+     * The actions actually offered for the object on screen.
+     *
+     * The catalogue at `/spark/actions/{objectTypeId}` is per TYPE -- the server is never told which
+     * row is open -- so an action that applies to only some rows cannot be filtered there. The
+     * entity's actions hook decides while it has the entity in hand and withholds what does not
+     * apply, and the object arrives carrying that answer.
+     *
+     * An affordance, not a permission: the endpoint stays reachable and the action handler still
+     * refuses on its own terms. What this prevents is offering a destructive action where it cannot
+     * possibly apply -- Coverage showed an irreversible red "Delete data" button on every repository
+     * page, healthy ones included, and only admitted it would refuse after the confirmation prompt.
+     */
+    visibleCustomActions: _angular_core.Signal<CustomActionDefinition[]>;
     constructor();
+    /**
+     * Applies patched attribute values in place, without a re-fetch.
+     *
+     * The operation carries the value the server computed after its own write, so this is both
+     * cheaper and more correct than re-reading: a re-read goes through a RavenDB index that may
+     * still be stale from the very write that produced the patch, and would show the old value.
+     */
+    private applyAttributePatches;
     private onParamsChange;
     visibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     private static readonly DEFAULT_TAB;
@@ -73,6 +96,16 @@ declare class SparkPoDetailComponent {
      * from a JSON file and must not be able to put arbitrary classes on the button.
      */
     protected customActionClass(action: CustomActionDefinition): string;
+    /**
+     * The action currently running, or null. Drives the disabled state on every custom-action
+     * button.
+     *
+     * A custom action is not necessarily quick: Coverage's Resync makes paged GitHub App calls for
+     * every account the caller manages, inside the request. Without this the button stayed live and
+     * looked inert for several seconds, and a second click queued a second full run -- which is how
+     * a slow action and a broken one became indistinguishable.
+     */
+    runningAction: _angular_core.WritableSignal<string | null>;
     onCustomAction(action: CustomActionDefinition): Promise<void>;
     onEdit(): void;
     onDelete(): Promise<void>;

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

@@ -42,6 +42,7 @@ declare class SparkStreamingService {
 }
 
 declare class SparkService {
+    #private;
     private readonly config;
     private readonly baseUrl;
     private readonly http;
@@ -53,6 +54,14 @@ declare class SparkService {
     getPermissions(entityTypeId: string): Promise<EntityPermissions>;
     getQueries(): Promise<SparkQuery[]>;
     getQuery(id: string): Promise<SparkQuery>;
+    /**
+     * Resolves a query by name, fetching the catalogue at most once per service instance.
+     *
+     * Without the cache this costs a full `GET /spark/queries` per call, and a form with several
+     * reference attributes resolves them in parallel — so opening one page fetched the whole query
+     * catalogue N times over. The catalogue is per-caller and effectively static for a page's
+     * lifetime; the service is scoped to the app, so a permission change lands on the next load.
+     */
     getQueryByName(name: string): Promise<SparkQuery | undefined>;
     executeQuery(queryId: string, options?: {
         sortColumns?: SortColumn[];
@@ -62,12 +71,23 @@ declare class SparkService {
         take?: number;
         search?: string;
     }): Promise<QueryResult>;
+    /**
+     * Runs a query identified by name.
+     *
+     * It used to forward only the parent, dropping skip/take/search — so every reference picker and
+     * AsDetail reference column silently saw the server's default of 50 candidates, with no indication
+     * that the list was cut. A picker that omits the option you are looking for, and says nothing, is
+     * worse than one that fails.
+     */
     executeQueryByName(queryName: string, options?: {
         parentId?: string;
         parentType?: string;
+        skip?: number;
+        take?: number;
+        search?: string;
+        sortColumns?: SortColumn[];
     }): Promise<QueryResult>;
     getProgramUnits(): Promise<ProgramUnitsConfiguration>;
-    list(type: string): Promise<PersistentObject[]>;
     get(type: string, id: string): Promise<PersistentObject>;
     create(type: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
     update(type: string, id: string, data: Partial<PersistentObject>): Promise<PersistentObject>;