@mintplayer/ng-spark 22.24.0 → 22.25.0

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

@@ -3,7 +3,8 @@ import { Type } from "@angular/core";
 import { CdkDragDrop } from "@angular/cdk/drag-drop";
 import { Color } from "@mintplayer/ng-bootstrap";
 import { InMemoryTreeSelectProvider, TreeNode } from "@mintplayer/ng-bootstrap/tree-select";
-import { AttributeGroup, AttributeTab, ELookupDisplayType, EReferenceDisplayType, EntityAttributeDefinition, EntityPermissions, EntityType, LookupReference, LookupReferenceValue, PersistentObject, QueryResultItem, RefreshOverlay, RuleFailure, ValidationError } from "@mintplayer/ng-spark/models";
+import { AttributeGroup, AttributeTab, ELookupDisplayType, EReferenceDisplayType, EntityAttributeDefinition, EntityPermissions, EntityType, LookupReference, LookupReferenceValue, PersistentObject, QueryResultItem, RefreshOverlay, RefreshTrigger, RuleFailure, ValidationError } from "@mintplayer/ng-spark/models";
+import { SparkResolvedRowRenderer } from "@mintplayer/ng-spark/renderers";
 import { DatatableSettings } from "@mintplayer/ng-bootstrap/datatable";
 import { PaginationResponse } from "@mintplayer/pagination";
 /** What the coordinator needs from its host, so it can be tested without mounting a form. */
@@ -35,6 +36,8 @@ declare class RefreshCoordinator {
   private sequence;
   private settled;
   private pending;
+  /** Debounce timers for `ValueChanged` free text, keyed by path. A path here is also in `pending`. */
+  private timers;
   constructor(host: RefreshCoordinatorHost);
   /** Whether a refresh is in flight. */
   get isRefreshing(): boolean;
@@ -43,26 +46,66 @@ declare class RefreshCoordinator {
    * would otherwise issue a request per keystroke. Flushed by {@link blur} or {@link flush}.
    */
   markPending(attributeName: string): void;
-  /** Sends a pending refresh for `attributeName`, if one was marked. */
+  /**
+   * Routes a change by its {@link RefreshDispatch}: send now, send once typing pauses, or wait for
+   * blur. The one entry point a form needs, so the three editors' policies live here.
+   */
+  dispatch(attributeName: string, mode: RefreshDispatch): Promise<void>;
+  /** Sends a pending refresh for `attributeName`, if one was marked (or is waiting on its debounce). */
   blur(attributeName: string): Promise<void>;
   /**
-   * Sends every refresh still marked pending. Called before save, so a value typed and never blurred
-   * — the user tabbing straight to the save button — is still reflected before the object goes.
+   * Sends every refresh still marked pending, including any waiting on a debounce. Called before
+   * save, so a value typed and never blurred — the user tabbing straight to the save button — is
+   * still reflected before the object goes.
    */
   flush(): Promise<void>;
-  /** Sends a refresh immediately — discrete editors, where every change is a committed one. */
-  trigger(attributeName: string): Promise<void>;
+  /** Drops every pending mark and debounce timer without sending — the form is going away. */
+  dispose(): void;
+  /**
+   * Sends a refresh — immediately for discrete editors, where every change is a committed one.
+   *
+   * With `debounceMs`, the send waits until `attributeName` has been quiet for that long; each call
+   * restarts the wait, so a burst of keystrokes costs one request. Until it fires, the path counts as
+   * pending, so {@link blur} and {@link flush} send it straight away instead of waiting out the timer.
+   */
+  trigger(attributeName: string, options?: {
+    debounceMs?: number;
+  }): Promise<void>;
+  private clearTimer;
 }
+/** How long `ValueChanged` free text waits for typing to pause before refreshing — like the search box. */
+declare const SPARK_REFRESH_DEBOUNCE_MS = 300;
 /** The subset of an attribute definition that decides how its editor behaves. */
 interface RefreshTriggerShape {
   dataType?: string;
   lookupReferenceType?: string;
   isArray?: boolean;
+  triggersRefresh?: RefreshTrigger;
 }
+/** When a change sends its refresh: on the change itself, on blur, or never. */
+type EffectiveRefreshTrigger = 'change' | 'blur' | 'none';
+/** How {@link RefreshCoordinator.dispatch} handles a change. */
+type RefreshDispatch = 'immediate' | 'debounced' | 'blur';
+/**
+ * Resolves the declared `triggersRefresh` against the editor the attribute renders as.
+ *
+ * - `None` / absent → `'none'`.
+ * - `Auto` → `'change'` for a discrete editor, `'blur'` for free text (the original behaviour).
+ * - `ValueChanged` → `'change'` (debounced for free text — see {@link refreshDispatch}).
+ * - `Blur` → `'blur'`, except on a discrete editor, which has no meaningful blur and so acts as
+ *   `ValueChanged`. The server's `--spark-verify-model` warns about that declaration.
+ */
+declare function effectiveTrigger(attr: RefreshTriggerShape | undefined): EffectiveRefreshTrigger;
+/**
+ * How a change to `attr` is sent, or `null` when it sends nothing. A `'change'` trigger on free
+ * text is debounced; on a discrete editor it is immediate.
+ */
+declare function refreshDispatch(attr: RefreshTriggerShape | undefined): RefreshDispatch | null;
+/** Whether the change to `attr` is sent immediately (a discrete editor with a change trigger). */
+declare function triggersImmediately(attr: RefreshTriggerShape | undefined): boolean;
 /**
- * Editors where every change is a deliberate, committed one, so a refresh fires immediately.
- * Everything else is free text, where firing per keystroke would be unacceptable and the refresh
- * waits for blur.
+ * Editors where every change is a deliberate, committed one. Everything else is free text, where
+ * firing per keystroke would be unacceptable.
  *
  * ⚠️ This asks how the attribute is **rendered**, not what its `dataType` says, and the difference
  * is not academic. A lookup attribute carries the data type of its *key* — Fleet's `Car.Status` is
@@ -70,24 +113,25 @@ interface RefreshTriggerShape {
  * classifies a `<bs-select>` as free text. It then waits for a blur that a select never emits, and
  * the refresh simply never fires: no request, no error, nothing to see.
  */
-declare function triggersImmediately(attr: RefreshTriggerShape | undefined): boolean;
+declare function isDiscreteEditor(attr: RefreshTriggerShape | undefined): boolean;
 /** Empty overlay, so callers do not have to spell the type. */
 declare const NO_OVERLAY: RefreshOverlay;
 /**
  * A refresh a form embedded in another form is asking its host to issue on its behalf.
  *
- * `immediate` mirrors the distinction the host's own editors make: a discrete editor fires on
- * change, free text only marks itself pending and fires on blur.
+ * `dispatch` carries the decision the child's own editor made from its declared `triggersRefresh`
+ * — send now, send once typing pauses, or wait for blur — so the host applies exactly the semantics
+ * it would have applied to an editor of its own.
  */
 export interface NestedTriggerRequest {
   /** The full path the server addresses, e.g. `Gate.ProjectMode`. */
   path: string;
-  immediate: boolean;
+  dispatch: RefreshDispatch;
 }
 export declare class SparkPoFormComponent {
   private readonly sparkService;
   private readonly translations;
-  private readonly rendererRegistry;
+  protected readonly rendererRegistry: import("@mintplayer/ng-spark/renderers").SparkAttributeRendererRegistration[];
   entityType: import("@angular/core").InputSignal<EntityType | null>;
   formData: import("@angular/core").ModelSignal<Record<string, any>>;
   validationErrors: import("@angular/core").InputSignal<ValidationError[]>;
@@ -200,6 +244,8 @@ export declare class SparkPoFormComponent {
   getEditRendererInputs(component: Type<any>, attr: EntityAttributeDefinition): Record<string, any>;
   /** Column renderer for a cell of an AsDetail sub-table (so embedded rows honor `col.renderer` too). */
   getAsDetailCellRendererComponent(col: EntityAttributeDefinition): Type<any> | null;
+  /** Inputs of an AsDetail row renderer (`rowComponent`): the row and the object being edited. */
+  getRowRendererInputs(renderer: SparkResolvedRowRenderer, row: Record<string, any>): Record<string, any>;
   getAsDetailCellRendererInputs(component: Type<any>, row: Record<string, any>, col: EntityAttributeDefinition): Record<string, any>;
   /** Edit-renderer for an inline AsDetail cell (so inline editing honors `col.renderer`, not just display). */
   getAsDetailCellEditRenderer(col: EntityAttributeDefinition): Type<any> | null;
@@ -259,7 +305,10 @@ export declare class SparkPoFormComponent {
    */
   private applyNestedResponse;
   onInlineCellBlur(attr: EntityAttributeDefinition, rowIndex: number, col: EntityAttributeDefinition): void;
-  /** Blur handler for free-text editors — sends the refresh their keystrokes only marked pending. */
+  /**
+   * Blur handler for free-text editors — sends the refresh their keystrokes only marked pending, or
+   * cuts short a `ValueChanged` debounce that is still waiting.
+   */
   onFieldBlur(attr: EntityAttributeDefinition): void;
   private noteChange;
   /** `Gate.ProjectMode` — the index-free counterpart of the inline grid's `Jobs[1].Kind`. */

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

@@ -3,7 +3,7 @@ import { TemplateRef } from "@angular/core";
 import { Color } from "@mintplayer/ng-bootstrap";
 import { SparkLanguageService } from "@mintplayer/ng-spark/services";
 import { SparkQueryToolbarAction } from "@mintplayer/ng-spark/grid";
-import { CustomActionDefinition, QueryColumn, QueryResultItem, SparkDeletedFilter } from "@mintplayer/ng-spark/models";
+import { CustomActionDefinition, QueryColumn, QueryColumnFilter, QueryResultItem, SparkDeletedFilter } from "@mintplayer/ng-spark/models";
 import { SparkQueryListContext } from "@mintplayer/ng-spark/panels";
 /**
  * The routed query page: chrome around one {@link SparkQueryGridComponent}.
@@ -96,6 +96,31 @@ export declare class SparkQueryListComponent {
    */
   protected readonly gridData: import("@angular/core").Signal<QueryResultItem[] | null>;
   constructor();
+  /**
+   * The parent the URL scopes the query to (`?parentId=…&parentType=…`), sent exactly as a sub-query
+   * sends its container. Both or neither: one without the other is ignored, as the server does.
+   */
+  protected readonly urlParentId: import("@angular/core").WritableSignal<string>;
+  protected readonly urlParentType: import("@angular/core").WritableSignal<string>;
+  /**
+   * Column filters from the URL: every other query-string parameter, `?Language=en&Script=Latn`
+   * (repeat a name for several values). The grid applies only those naming an attribute of the
+   * query's type; the rest are ignored. This is the contributions History link's shape, and works for
+   * any query.
+   */
+  protected readonly urlFilters: import("@angular/core").WritableSignal<QueryColumnFilter[]>;
+  /** The URL filters the grid applied, as removable chips. */
+  protected readonly activeUrlFilters: import("@angular/core").Signal<QueryColumnFilter[]>;
+  /** Query-string names the page or the row links own, never column filters. */
+  private static readonly reservedParams;
+  private applyUrlScope;
+  /** Drops one URL filter (its query-string parameter); the grid refetches. */
+  protected clearUrlFilter(name: string): void;
+  /** Drops the parent and every URL filter. */
+  protected clearUrlScope(): void;
+  protected filterValues(filter: QueryColumnFilter): string;
+  /** The column's label for a chip: the query's own column label, else the attribute's, else its name. */
+  protected filterLabel(name: string): string;
   private onParamsChange;
   /**
    * A load failure has to render, not just be swallowed: a denied query answers 404 (audit M-3, so

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

@@ -1,5 +1,5 @@
 import { InjectionToken, InputSignal, Provider, Type } from "@angular/core";
-import { EntityAttributeDefinition, PersistentObject, PersistentObjectAttribute, QueryResultItem, QueryResultItemValue, SparkCellColumn } from "@mintplayer/ng-spark/models";
+import { EntityAttributeDefinition, EntityType, PersistentObject, PersistentObjectAttribute, QueryResultItem, QueryResultItemValue, SparkCellColumn } from "@mintplayer/ng-spark/models";
 /**
  * Drops entries the component doesn't declare, so every contract member is
  * genuinely optional — NgComponentOutlet throws on an undeclared input.
@@ -72,6 +72,21 @@ export interface SparkAttributeColumnRenderer {
    */
   item?: InputSignal<QueryResultItem | Record<string, any> | undefined>;
 }
+/**
+ * Contract for AsDetail **row** renderers (`rowComponent` of a registration): drawn once per row of an
+ * AsDetail table, on the detail page and in the edit form, for the row-type attributes carrying the
+ * renderer — which are then not drawn as columns.
+ */
+export interface SparkAttributeRowRenderer {
+  /** The row: a flat record of the row's values (reserved `__spark…` keys included). */
+  row?: InputSignal<Record<string, any>>;
+  /** The row-type attributes carrying this renderer, in model order. */
+  attributes?: InputSignal<EntityAttributeDefinition[]>;
+  /** `rendererOptions` of the first of them. */
+  options?: InputSignal<Record<string, any> | undefined>;
+  /** The id of the object that owns the AsDetail list (undefined on a create page). */
+  ownerId?: InputSignal<string | undefined>;
+}
 /**
  * Contract for edit-form renderers (spark-po-form on create/edit pages).
  * Replaces the default <input> for this attribute.
@@ -98,6 +113,16 @@ export interface SparkAttributeRendererRegistration {
   columnComponent?: Type<any> | null;
   /** Optional component for create/edit forms. Must implement SparkAttributeEditRenderer. When omitted, the default input is used. */
   editComponent?: Type<any>;
+  /**
+   * A **row** renderer for AsDetail tables (the PO detail page and the edit form). Attributes of a row
+   * type that carry this renderer are not drawn as columns; instead the component is drawn ONCE per
+   * row, under the row's first cell, given all of them. Must implement {@link SparkAttributeRowRenderer}.
+   *
+   * For facts about a row rather than columns of it — contributions' "by Alice · 3 days ago ·
+   * History (4)" line collapses three read-only attributes into one. `rendererOptions` are taken from
+   * the first such attribute (a library writes the same options on each).
+   */
+  rowComponent?: Type<any>;
   /**
    * Relabels this column's values in a filter panel (#431).
    *
@@ -122,4 +147,21 @@ export declare const SPARK_ATTRIBUTE_RENDERERS: InjectionToken<SparkAttributeRen
  *   { name: 'color-swatch', detailComponent: ColorDetailComponent, columnComponent: ColorColumnComponent },
  * ])
  */
-export declare function provideSparkAttributeRenderers(renderers: SparkAttributeRendererRegistration[]): Provider;
+export declare function provideSparkAttributeRenderers(renderers: SparkAttributeRendererRegistration[]): Provider;
+/** The row renderer of an AsDetail row type, resolved once per type (see `rowComponent`). */
+export interface SparkResolvedRowRenderer {
+  component: Type<any>;
+  /** The row-type attributes carrying the renderer, in model order. */
+  attributes: EntityAttributeDefinition[];
+  /** `rendererOptions` of the first of them. */
+  options: Record<string, any> | undefined;
+}
+/** Whether `attribute` is drawn by a row renderer (and therefore not as a column). */
+export declare function isRowRendered(attribute: EntityAttributeDefinition, registry: readonly SparkAttributeRendererRegistration[] | null | undefined): boolean;
+/**
+ * The first row renderer the row type's visible attributes name, or null. One per row: a row type
+ * whose attributes name two different row renderers gets the first in model order.
+ */
+export declare function resolveRowRenderer(rowType: EntityType | null | undefined, registry: readonly SparkAttributeRendererRegistration[] | null | undefined): SparkResolvedRowRenderer | null;
+/** The input bag for a row renderer, filtered to what the component declares. */
+export declare function rowRendererInputs(renderer: SparkResolvedRowRenderer, row: Record<string, any>, ownerId: string | undefined): Record<string, any>;

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

@@ -1,6 +1,7 @@
 import * as i0 from "@angular/core";
 import { TemplateRef } from "@angular/core";
 import { BsShellState } from "@mintplayer/ng-bootstrap/shell";
+import { BsThemeService, BsThemeToggleMode } from "@mintplayer/ng-bootstrap/theming";
 import { Breakpoint } from "@mintplayer/ng-bootstrap";
 import { ShellStateChangeEventDetail } from "@mintplayer/web-components/shell";
 import { ProgramUnitGroup } from "@mintplayer/ng-spark/models";
@@ -180,10 +181,16 @@ export declare class SparkShellMainHeaderDirective {
  * listens to `statechange` to keep the toggler's icon truthful in `auto` mode and only forces
  * `show`/`hide` on explicit toggles.
  *
- * Theming: the chrome colors are CSS custom properties with the classic dark-sidebar defaults —
- * `--spark-shell-topbar-bg`, `--spark-shell-sidebar-bg`, `--spark-shell-main-bg` — overridable on
- * the `<spark-shell>` element. `sidebarTheme` flips the sidebar's `data-bs-theme` (which is what
- * recolors the accordion internals across the shadow boundary) together with its default palette.
+ * Theming: the chrome colors are CSS custom properties —
+ * `--spark-shell-{topbar,sidebar,main}-{bg,color}` — declared per colour scheme under
+ * `[data-bs-theme=light]` / `[data-bs-theme=dark]` from Bootstrap tokens, so the whole shell follows
+ * the page's theme. An app restyles it by overriding those tokens, globally per scheme or on the
+ * `<spark-shell>` element.
+ *
+ * Colour mode: the shell injects `BsThemeService` itself, so 'auto' follows the OS live even when
+ * the topbar toggle is hidden with `[themeToggle]="false"` (an app may then place its own
+ * `<bs-theme-toggle>` elsewhere). The first paint is themed by `bs-theme-preboot.js` in the app's
+ * `index.html`, not by anything here.
  */
 export declare class SparkShellComponent {
   /** The sidebar heading. Ignored when a `*sparkShellSidebarHeader` slot is supplied. */
@@ -191,10 +198,18 @@ export declare class SparkShellComponent {
   /** Forwarded to `bs-shell`: below it the sidebar is an overlay drawer. */
   readonly breakpoint: import("@angular/core").InputSignal<Breakpoint>;
   /**
-   * `data-bs-theme` for the sidebar — what flips the accordion's shadow-DOM internals between
-   * palettes — plus the matching default background. `null` sets no theme (inherit the page's).
+   * Render the Auto / Light / Dark `bs-theme-toggle` in the topbar. `false` hides it; the theme
+   * service stays live either way.
+   */
+  readonly themeToggle: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Instantiated here, not only through the toggle (PRD D3): without it, `[themeToggle]="false"`
+   * would leave 'auto' with no live `prefers-color-scheme` listener in Angular's view.
    */
-  readonly sidebarTheme: import("@angular/core").InputSignal<"dark" | "light" | null>;
+  protected readonly theme: BsThemeService;
+  private readonly lang;
+  /** The toggle's cycle with Spark's translated labels (`theme.*` keys); icons stay ng-bootstrap's. */
+  protected readonly themeModes: import("@angular/core").Signal<readonly BsThemeToggleMode[]>;
   /** Forwarded to the menu: any changed value re-fetches the program units. */
   readonly reloadToken: import("@angular/core").InputSignal<unknown>;
   /** Extra sidebar tabs as data, for hosts that compute them; `*sparkShellTab` is the usual way. */
@@ -244,8 +259,8 @@ export declare class SparkShellComponent {
       "required": false;
       "isSignal": true;
     };
-    "sidebarTheme": {
-      "alias": "sidebarTheme";
+    "themeToggle": {
+      "alias": "themeToggle";
       "required": false;
       "isSignal": true;
     };

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

@@ -1,6 +1,18 @@
 import { InjectionToken, Provider, Signal } from "@angular/core";
 interface SparkConfig {
   baseUrl: string;
+  /**
+   * The concurrency-conflict notice and dialog on the edit page.
+   *
+   * `showChangedBy`: when true, "Changed by X" names whoever wrote the version merged against, but
+   * only when History resolves a display name for exactly that version (a `History/T` holder; one
+   * `POST /spark/po/revisions` request). Default false: no History request is made and no user is
+   * shown. A raw `ModifiedBy` user id is never shown in either mode. The "at T" time part is shown
+   * whenever the object carries `ModifiedAt`.
+   */
+  conflictDialog?: {
+    showChangedBy?: boolean;
+  };
 }
 export declare const SPARK_CONFIG: InjectionToken<SparkConfig>;
 export declare const defaultSparkConfig: SparkConfig;