@mintplayer/ng-spark 22.10.0 → 22.12.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.

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.
@@ -452,6 +484,15 @@ interface CustomActionDefinition {
     selectionRule?: string;
     refreshOnCompleted: boolean;
     confirmationMessageKey?: string;
+    /**
+     * How prominently, and how warily, to present the action: 'primary', 'secondary', 'danger',
+     * 'warning'. Undefined renders the neutral default.
+     *
+     * Presentation only — the server decides who may see and run an action. A 'danger' variant just
+     * asks the button to look like what it does; pair it with `confirmationMessageKey` for anything
+     * irreversible, because the colour warns and the prompt is what actually prevents the accident.
+     */
+    variant?: string;
     offset: number;
 }
 

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;
@@ -66,6 +89,23 @@ declare class SparkPoDetailComponent {
     getAsDetailCellRendererInputs(component: Type<any>, row: Record<string, any>, col: EntityAttributeDefinition): Record<string, any>;
     private loadLookupReferenceOptions;
     private loadAsDetailTypes;
+    /**
+     * The bootstrap classes for a custom action's button. Outline-primary stays the default, so
+     * every existing action looks exactly as it did; a server-declared variant opts one action into
+     * a louder style. Restricted to a known set rather than interpolated, because the value arrives
+     * 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-query-list.d.ts

@@ -61,6 +61,8 @@ declare class SparkQueryListComponent {
     protected readonly isVirtualScrolling: _angular_core.Signal<boolean>;
     protected readonly gridError: _angular_core.Signal<string | null>;
     /** Whether an action's selection rule is satisfied. Delegated: the grid holds the selection. */
+    /** @see SparkPoDetailComponent.customActionClass — same allow-list, same default. */
+    protected customActionClass(action: CustomActionDefinition): string;
     protected isActionEnabled(action: CustomActionDefinition): boolean;
     isStreaming: _angular_core.WritableSignal<boolean>;
     private streamingSub;

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>;