@mintplayer/ng-spark 22.28.1 → 22.30.0

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

@@ -53,6 +53,12 @@ export interface RetryOperation {
   defaultOption?: string | null;
   persistentObject?: PersistentObject | null;
   message?: string | null;
+  /** Whether the client offers its own translated Cancel, answered as `'Cancel'` (`IRetryAccessor.Action(..., cancellable)`). */
+  cancellable?: boolean;
+  /** A client method to run instead of a modal (`IRetryAccessor.Invoke`); see `provideSparkClientMethods`. */
+  clientMethod?: string | null;
+  /** Its argument, as the server serialized it. */
+  arguments?: unknown;
 }
 /**
  * Discriminated union of known operation types, plus an open shape for unknown
@@ -120,6 +126,70 @@ export interface ClientOperationHandlerRegistration {
  * providers using this token.
  */
 export declare const SPARK_CLIENT_OPERATION_HANDLERS: InjectionToken<readonly ClientOperationHandlerRegistration[]>;
+/**
+ * One step a server action needs from the browser (`IRetryAccessor.Invoke` on the server): WebAuthn,
+ * a file picker, the clipboard. The answer travels back into the same server action as the retry's
+ * `value`, so authorization, state and the follow-up all stay inside that one action.
+ */
+export interface SparkClientMethod {
+  /**
+   * Runs the step. Called in an injection context, so `inject()` works synchronously at the top.
+   * A rejection or a thrown error answers the server with `Cancel`, exactly like an unknown name.
+   */
+  invoke(args: unknown): Promise<unknown>;
+  /**
+   * Whether this browser can run the method at all. An action whose `requiresClient` names a method
+   * that is unsupported is shown disabled; an `Invoke` of it answers `Cancel` without running it.
+   * Absent means always supported.
+   */
+  supported?(): boolean;
+  /** The translation key explaining why the method is unsupported; defaults to `common.clientUnsupported`. */
+  unsupportedReason?: string;
+}
+/** Client methods by the name the server invokes them with, e.g. `{ 'webauthn.create': { invoke: … } }`. */
+export type SparkClientMethodMap = Readonly<Record<string, SparkClientMethod>>;
+/** Multi-provider token; use {@link provideSparkClientMethods}. A later registration of a name wins. */
+export declare const SPARK_CLIENT_METHODS: InjectionToken<readonly Readonly<Record<string, SparkClientMethod>>[]>;
+/** The reason shown on an action whose client method is missing or unsupported, when the method names none. */
+export declare const SPARK_CLIENT_UNSUPPORTED_REASON = "common.clientUnsupported";
+/**
+ * Registers client methods a server action may invoke through a retry (`IRetryAccessor.Invoke`).
+ *
+ * The set is closed on purpose: the server can only name a method the app registered here, and an
+ * unknown name answers `Cancel`. Nothing the server sends is evaluated.
+ *
+ * @example
+ * provideSparkClientMethods({
+ *   'clipboard.read': { invoke: () => navigator.clipboard.readText(), supported: () => !!navigator.clipboard },
+ * })
+ */
+export declare function provideSparkClientMethods(methods: SparkClientMethodMap): EnvironmentProviders;
+/** How a client method ended: its value, or a failure the server sees as `Cancel`. */
+export type SparkClientMethodOutcome = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+};
+/** The registered client methods: whether one can run here, and running it. */
+export declare class SparkClientMethodRegistry {
+  private readonly injector;
+  private readonly methods;
+  constructor();
+  /**
+   * Null when the method is registered and supported here; otherwise the translation key saying why
+   * it is not. Null for no name at all, so an action without `requiresClient` is never affected.
+   */
+  unavailableReason(name: string | null | undefined): string | null;
+  /**
+   * Runs the method registered under `name`. Fails closed: an unknown name, an unsupported method, a
+   * rejection or a thrown error all end as `{ ok: false }`, which the retry loop answers as `Cancel`.
+   */
+  invoke(name: string, args: unknown): Promise<SparkClientMethodOutcome>;
+  private isSupported;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkClientMethodRegistry, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
 export interface SparkToast {
   id: string;
   message: string;
@@ -184,17 +254,24 @@ export declare function provideSparkClientOperations(): EnvironmentProviders;
  */
 export declare class SparkQueryRefreshService {
   private readonly tokens;
-  /** Bumped every time the server asks for this query to refresh. */
+  /**
+   * Bumped every time a refresh is asked for this key.
+   *
+   * ⚠️ Reading it makes the caller depend on EVERY key, not just this one: the counters share one
+   * signal. A grid must therefore compare the value with the one it last saw, never react to the
+   * read alone (#319) — otherwise it re-fetches for every query refreshed anywhere in the app.
+   */
   tokenFor(queryId: string | undefined): number;
   /**
    * Ask every grid showing `queryId` to re-fetch.
    *
-   * Matched on the EXACT string a grid passes to {@link tokenFor} -- whichever of id or alias
-   * its `queryId` input holds. A caller that knows only the other form will not reach it.
+   * `queryId` is the query's id or its alias. A grid answers to both, whichever its own `queryId`
+   * input holds, because it learns the other from the query it resolved. Keys are matched
+   * case-insensitively, as the server resolves them (`QueryLoader.ResolveQuery`).
    *
    * Callers bumping several keys for one user action should do so in one synchronous run: the
    * signal coalesces bumps within a tick into a single effect run, and bumps split across an
-   * await become one re-fetch each.
+   * await become one re-fetch each (#319).
    */
   request(queryId: string): void;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryRefreshService, never>;

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

@@ -252,6 +252,7 @@ export declare class SparkQueryGridComponent {
   /** Add-on row-menu entries (`SPARK_QUERY_ROW_ACTIONS`), e.g. Contributions' revert. */
   private readonly addonRowActions;
   readonly lang: SparkLanguageService;
+  private readonly clientMethods;
   /** Query alias or id. */
   queryId: import("@angular/core").InputSignal<string>;
   /**
@@ -430,6 +431,11 @@ export declare class SparkQueryGridComponent {
   offersCreate: import("@angular/core").Signal<boolean>;
   visibleCustomActions: import("@angular/core").Signal<CustomActionDefinition[]>;
   fetchFn: import("@angular/core").WritableSignal<BsDatatableFetch<QueryResultItem> | null>;
+  /**
+   * The grid's own datatable, for {@link reload}. A `viewChild` is safe here: the `@if` concern above
+   * is about hosts holding this grid, while this is the grid's own template, read only on demand.
+   */
+  private readonly datatable;
   /**
    * Why the component renders its own failure instead of only reporting one.
    *
@@ -544,6 +550,13 @@ export declare class SparkQueryGridComponent {
    * Every column that ships is drawn (#264): there is no shipped-but-hidden column.
    */
   allColumns: import("@angular/core").Signal<QueryColumn[]>;
+  /** The internal name of the per-row ⋮ menu's column; never shown or announced (its `label` is "Actions"). */
+  readonly rowActionsColumn = "__sparkRowActions";
+  /**
+   * The datatable's `[labels]`: the resize handle and its options dialog, translated. The column
+   * each string names comes from `bsDatatableColumnLabel` in the template. See `sparkDatatableLabels`.
+   */
+  datatableLabels: import("@angular/core").Signal<import("@mintplayer/ng-spark/services").SparkDatatableLabels>;
   /**
    * True when rows do not come from this component's own fetch.
    *
@@ -554,8 +567,16 @@ export declare class SparkQueryGridComponent {
    * before the host had anything to bind.
    */
   hasExternalData: import("@angular/core").Signal<boolean>;
-  /** Whether an action's selection rule is satisfied right now. The server checks it again. */
+  /**
+   * Whether an action can run right now: its selection rule is satisfied, and the client method it
+   * requires (`requiresClient`) is registered and supported here. The server checks the rule again.
+   */
   isActionEnabled(action: CustomActionDefinition): boolean;
+  /**
+   * Why an action is disabled regardless of the selection, translated, for its tooltip: its required
+   * client method is missing or unsupported in this browser (Q9). Null when nothing stands in the way.
+   */
+  actionUnavailableReason(action: CustomActionDefinition): string | null;
   constructor();
   /**
    * Re-run the query, keeping the current page, sort and scroll position.
@@ -563,8 +584,15 @@ export declare class SparkQueryGridComponent {
    * 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.
+   *
+   * Through the datatable's own `reload()` (mintplayer-ng-bootstrap#407), which re-queries the
+   * current page and coalesces calls within a microtask. Swapping the `[fetch]` identity, the only
+   * way before it existed, also disarmed the datatable's reload dedupe. The swap stays as the
+   * fallback while the datatable is not rendered (loading), where a fresh closure is what counts.
    */
-  reload(): void;
+  reload(options?: {
+    resetPage?: boolean;
+  }): void;
   private onSearchChanged;
   /**
    * Replaces the fetched columns only when they actually differ.
@@ -627,11 +655,13 @@ export declare class SparkQueryGridComponent {
    */
   protected onFilterChange(detail: FilterChangeDetail): void;
   /**
-   * Back to page 1 and a fresh fetch identity, exactly as a new search term does.
+   * Back to page 1 and a forced re-fetch.
    *
    * Both halves matter: the old page number means nothing against a different result set, and the
    * datatable dedupes reloads by `(page, perPage, sort)` — none of which a filter changes — so
-   * without a new fetch identity the request is silently never made.
+   * without forcing it the request is silently never made. `resetPage` makes the datatable fetch
+   * page 1 itself: the settings binding reaches it only on the next change detection, after the
+   * reload already fetched.
    */
   private onFilterChanged;
   /**
@@ -858,6 +888,8 @@ export declare class SparkQueryCardComponent {
   protected readonly toolbarActions: import("@angular/core").Signal<SparkQueryToolbarAction[]>;
   protected actionClass(action: SparkQueryToolbarAction): string;
   protected isEnabled(action: SparkQueryToolbarAction): boolean;
+  /** The tooltip of an action disabled for want of its client method (`requiresClient`); null otherwise. */
+  protected unavailableReason(action: SparkQueryToolbarAction): string | null;
   protected run(action: SparkQueryToolbarAction): void;
   protected readonly selection: import("@angular/core").Signal<QueryResultItem[]>;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryCardComponent, never>;

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

@@ -169,6 +169,12 @@ export interface CustomActionDefinition {
    * `/po/new`, the edit page and `/po/delete-many`, never `/actions/execute`. Absent for a custom action.
    */
   isDefault?: boolean;
+  /**
+   * The client method the action needs in the browser (`provideSparkClientMethods`), e.g.
+   * `'webauthn.create'`. When it is not registered, or its `supported()` says no, the action is shown
+   * disabled with the reason as its tooltip. Advisory: the server still handles a cancelled step.
+   */
+  requiresClient?: string;
 }
 /**
  * Whether a grid lets the user tick rows — what `<bs-datatable>` renders. There is no single
@@ -665,19 +671,41 @@ export interface LookupReferenceValue {
   isActive: boolean;
   extra?: Record<string, unknown>;
 }
+/**
+ * The option a cancelled retry step answers with (`RetryResult.CancelOption` on the server): the
+ * modal's own Cancel button or its dismissal on a `cancellable` prompt, and a client method that did
+ * not answer. An identifier, never a label: the button shows `common.cancel` in the user's language.
+ */
+export declare const SPARK_RETRY_CANCEL = "Cancel";
 export interface RetryActionPayload {
   type: 'retry-action';
   step: number;
   title: string;
   message?: string;
+  /** The action's own options, shown as given. Never `'Cancel'`: see {@link cancellable}. */
   options: string[];
   defaultOption?: string;
   persistentObject?: PersistentObject;
+  /**
+   * Whether the modal adds its own Cancel button, labelled `common.cancel`, which, like closing the
+   * modal, answers {@link SPARK_RETRY_CANCEL}. Without it a closed modal abandons the request.
+   */
+  cancellable?: boolean;
+  /**
+   * Set when the server asks for a client method (`IRetryAccessor.Invoke`) instead of a choice: the
+   * name a method was registered under with `provideSparkClientMethods`. No modal is shown then.
+   */
+  clientMethod?: string;
+  /** The client method's argument, as the server serialized it. */
+  arguments?: unknown;
 }
 export interface RetryActionResult {
   step: number;
+  /** The option chosen. For a client-method step `'OK'` when it answered, `'Cancel'` otherwise. */
   option: string;
   persistentObject?: PersistentObject;
+  /** What the client method resolved with; absent for an ordinary prompt and for a cancelled step. */
+  value?: unknown;
 }
 export interface EntityPermissions {
   /**

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

@@ -13,6 +13,7 @@ export declare class SparkPoDetailComponent {
   private readonly queryRefresh;
   private readonly attributeRefresh;
   protected readonly lang: SparkLanguageService;
+  private readonly clientMethods;
   protected readonly rendererRegistry: import("@mintplayer/ng-spark/renderers").SparkAttributeRendererRegistration[];
   /**
    * Add-on panels and action-bar buttons (#460, `SPARK_DETAIL_PANELS` / `SPARK_DETAIL_ACTIONS`).
@@ -118,6 +119,8 @@ export declare class SparkPoDetailComponent {
   resolvedTabs: import("@angular/core").Signal<AttributeTab[]>;
   groupsForTab(tab: AttributeTab): AttributeGroup[];
   attrsForGroup(group: AttributeGroup): EntityAttributeDefinition[];
+  /** Whether the attribute's renderer asks for the whole row, without a label (`fullWidth`). */
+  isFullWidthRenderer(attr: EntityAttributeDefinition): boolean;
   getDetailRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;
   /** Inputs of an AsDetail row renderer (`rowComponent`): the row and the object that owns it. */
   getRowRendererInputs(renderer: SparkResolvedRowRenderer, row: Record<string, any>, item: PersistentObject): Record<string, any>;
@@ -146,6 +149,11 @@ export declare class SparkPoDetailComponent {
    * a slow action and a broken one became indistinguishable.
    */
   runningAction: import("@angular/core").WritableSignal<string | null>;
+  /**
+   * Why an action cannot run in this browser, translated, for its tooltip: the client method it
+   * requires (`requiresClient`) is not registered or not supported here (Q9). Null otherwise.
+   */
+  protected customActionUnavailableReason(action: CustomActionDefinition): string | null;
   onCustomAction(action: CustomActionDefinition): Promise<void>;
   onEdit(): void;
   onDelete(): Promise<void>;

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

@@ -516,6 +516,8 @@ export declare class SparkReferencePickerComponent {
   searchTerm: string;
   /** The picker lists query rows, so its columns are the query's: `showedOn` includes Query (#264; not None). */
   visibleAttributes: import("@angular/core").Signal<import("@mintplayer/ng-spark/models").EntityAttributeDefinition[]>;
+  /** The resize handle and its options dialog, translated; columns are named by `bsDatatableColumnLabel`. */
+  datatableLabels: import("@angular/core").Signal<import("@mintplayer/ng-spark/services").SparkDatatableLabels>;
   rows: import("@angular/core").Signal<QueryResultItem[]>;
   displayValue: import("@angular/core").Signal<string>;
   open(): Promise<void>;

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

@@ -85,6 +85,8 @@ export declare class SparkQueryListComponent {
   protected readonly toolbarActions: import("@angular/core").Signal<SparkQueryToolbarAction[]>;
   protected toolbarActionClass(action: SparkQueryToolbarAction): string;
   protected isToolbarActionEnabled(action: SparkQueryToolbarAction): boolean;
+  /** The tooltip of an action disabled for want of its client method (`requiresClient`); null otherwise. */
+  protected toolbarActionUnavailableReason(action: SparkQueryToolbarAction): string | null;
   protected runToolbarAction(action: SparkQueryToolbarAction): void;
   protected isActionEnabled(action: CustomActionDefinition): boolean;
   isStreaming: import("@angular/core").WritableSignal<boolean>;

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

@@ -1,3 +1,4 @@
+import * as i0 from "@angular/core";
 import { InjectionToken, InputSignal, Provider, Type } from "@angular/core";
 import { EntityAttributeDefinition, EntityType, PersistentObject, PersistentObjectAttribute, QueryResultItem, QueryResultItemValue, SparkCellColumn } from "@mintplayer/ng-spark/models";
 /**
@@ -136,7 +137,17 @@ export interface SparkAttributeRendererRegistration {
    * give it, which is the whole reason the renderer itself cannot be used here.
    */
   filterLabel?: (value: unknown) => string;
+  /**
+   * The detail page draws the renderer across the whole row, with no label: for text blocks such
+   * as the core `paragraph` renderer, which are body text rather than a labelled value.
+   */
+  fullWidth?: boolean;
 }
+/**
+ * The renderers ng-spark ships itself, available in every app without registration. An app's own
+ * registration of the same name wins (it comes first in the list).
+ */
+export declare const sparkCoreRenderers: readonly SparkAttributeRendererRegistration[];
 export declare const SPARK_ATTRIBUTE_RENDERERS: InjectionToken<SparkAttributeRendererRegistration[]>;
 /**
  * Register custom attribute renderers globally.
@@ -148,6 +159,42 @@ export declare const SPARK_ATTRIBUTE_RENDERERS: InjectionToken<SparkAttributeRen
  * ])
  */
 export declare function provideSparkAttributeRenderers(renderers: SparkAttributeRendererRegistration[]): Provider;
+/**
+ * The core `paragraph` renderer (generic passkeys page, D5): a read-only string shown as body text,
+ * full width and without a label — an explanatory text block on a persistent object, filled from
+ * translations by the actions class. Pair it with `showedOn: PersistentObject` so it never becomes a
+ * grid column.
+ *
+ * **Escaped by default.** The value is interpolated, so markup in it is shown as text. A blank line
+ * starts a new paragraph and a single newline is a line break.
+ *
+ * `"rendererOptions": { "sanitize": false }` renders the value as HTML instead, through Angular's
+ * `[innerHTML]`, whose sanitizer still strips scripts, event handlers and `javascript:` URLs. There is
+ * deliberately no `bypassSecurityTrustHtml` anywhere on this path: the opt-out is "allow markup",
+ * never "allow script".
+ */
+export declare class SparkParagraphRendererComponent implements SparkAttributeDetailRenderer {
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly text: import("@angular/core").Signal<string>;
+  /** Only an explicit `false` opts out of escaping; anything else, absent included, escapes. */
+  protected readonly asHtml: import("@angular/core").Signal<boolean>;
+  /** Paragraphs split on blank lines, each a list of its lines. */
+  protected readonly paragraphs: import("@angular/core").Signal<string[][]>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkParagraphRendererComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkParagraphRendererComponent, "spark-paragraph-renderer", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
 /** The row renderer of an AsDetail row type, resolved once per type (see `rowComponent`). */
 export interface SparkResolvedRowRenderer {
   component: Type<any>;

package/types/mintplayer-ng-spark-retry-action-modal.d.ts

@@ -15,6 +15,7 @@ export declare class SparkRetryActionModalComponent {
   protected readonly retryActionService: RetryActionService;
   private readonly sparkService;
   colors: typeof Color;
+  protected readonly cancel = "Cancel";
   isOpen: import("@angular/core").Signal<boolean>;
   /**
    * EntityType definition for the incoming PO — fetched lazily via SparkService so the

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

@@ -102,6 +102,7 @@ export declare class SparkService {
    */
   private static readonly MAX_RETRY_DEPTH;
   private readonly dispatcher;
+  private readonly clientMethods;
   getEntityTypes(): Promise<EntityType[]>;
   /**
    * One entity type, shaped by the caller's attribute rights. `purpose` narrows it for one form (#264, G1/G2):
@@ -492,4 +493,29 @@ export declare class SparkReturnNavigationService {
   listRouteFor(entityTypeName: string): Promise<unknown[] | null>;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkReturnNavigationService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
-}
+}
+/** The `<bs-datatable>` strings Spark translates: the column-resize handle and its options dialog. */
+export interface SparkDatatableLabels {
+  resizeColumn: (column: string) => string;
+  resizeColumnHint: string;
+  resizeColumnOptions: (column: string) => string;
+  narrowerColumn: (column: string) => string;
+  widerColumn: (column: string) => string;
+  columnWidth: (px: number) => string;
+  fitColumn: string;
+  resetColumn: string;
+}
+/**
+ * The `[labels]` a Spark `<bs-datatable>` passes so the column-resize handle, its keymap
+ * announcement and its resize options dialog (ng-bootstrap 22.22.0 / web-components 2.19.0) speak
+ * the viewer's language.
+ *
+ * The `column` these formatters receive is the column's label: every Spark grid binds
+ * `bsDatatableColumnLabel` to the header's translated text (and the row-actions column to
+ * "Actions"), so the datatable no longer falls back to the internal name. The keys omitted here
+ * keep the web component's English defaults.
+ *
+ * Every translation is read EAGERLY, so a `computed` that calls this tracks the language and the
+ * translation map, and hands the datatable a new object — which re-renders it — when either changes.
+ */
+export declare function sparkDatatableLabels(lang: SparkLanguageService): SparkDatatableLabels;