@mintplayer/ng-spark 22.16.0 → 22.18.0

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

@@ -53,6 +53,16 @@ interface PersistentObject {
     name: string;
     objectTypeId: string;
     breadcrumb?: string;
+    /**
+     * Optimistic-concurrency token -- RavenDB's change vector for the document behind this object.
+     * The server stamps it on every `/po/load` and expects it back on update.
+     *
+     * ⚠️ The check is opt-in BY PRESENCE of this field. Dropping it does not fail loudly; it makes
+     * the save unconditional, so two people editing the same record both succeed and the second
+     * silently overwrites the first. That is what used to happen here: `SparkClient` round-tripped
+     * the token and got a 409, the browser did not and got last-write-wins, on the same endpoint.
+     */
+    etag?: string;
     attributes: PersistentObjectAttribute[];
     /** Per-row edit/delete affordances; undefined = fall back to type-level permissions. */
     can?: PersistentObjectPermissions;
@@ -250,6 +260,23 @@ interface EntityType {
      * `queries` or `alias`.
      */
     detailTypes?: EntityType[];
+    /**
+     * Whether adding or removing a row of this type asks the server first.
+     *
+     * Absent or false — the default — keeps the purely client-side behaviour: New pushes a blank row,
+     * Delete splices it out, and the parent's save is the first the server hears of either. On, the
+     * grid calls `newObject` before showing a row and `deleteRow` before removing one, so
+     * `OnNewAsync` can default it and the delete hook can refuse.
+     *
+     * ⚠️ Read it off the **row type**, never the parent: the type that owns the hooks owns the
+     * decision. For a row type resolved out of `detailTypes` the flag survives the server-side
+     * pruning, so both sources agree.
+     *
+     * ⚠️ It governs the round trip and nothing else. It is not a permission, and it is outside the
+     * model hash, so nothing that gates a write may be conditional on it — the save path enforces the
+     * row type's New/Edit/Delete rights on every embedded collection whether this is on or off.
+     */
+    serverSideRowLifecycle?: boolean;
 }
 
 type SparkQueryRenderMode = 'Pagination' | 'VirtualScrolling';
@@ -535,6 +562,70 @@ interface StreamingErrorMessage {
 }
 type StreamingMessage = StreamingSnapshotMessage | StreamingPatchMessage | StreamingErrorMessage;
 
+/**
+ * Conversions between the wire format for a timestamp and what an `<input type="datetime-local">`
+ * or `<input type="date">` will accept.
+ *
+ * A `DateTimeOffset` in Spark means an **instant**. The wire carries a full ISO-8601 string with an
+ * offset (`2026-12-31T23:59:00-08:00`); an HTML date/time control speaks only bare local wall clock
+ * (`2026-12-31T23:59`). Neither end can consume the other's format, so both directions need
+ * converting, and the browser is deliberately the side that does it: its timezone rules are kept
+ * fresh by the operating system, while a container's are frozen at image build time.
+ *
+ * Assigning a wire value straight to a `datetime-local` input does not throw and does not warn -- the
+ * control simply renders **blank**, and saving the untouched form then writes that blank back.
+ */
+/**
+ * Parses a wire timestamp. Returns `null` for anything unusable, matching the contract of
+ * `parsedDate` / `queryCellValue` -- a bad value renders as empty rather than as `Invalid Date`.
+ */
+declare function parseWireDate(value: unknown): Date | null;
+/**
+ * Wire value -> the `yyyy-MM-ddTHH:mm` a `datetime-local` input needs, in the **viewer's** zone.
+ *
+ * The conversion is date-sensitive, not a fixed shift: a value is rendered using the zone's offset
+ * *on that value's own date*, so a timestamp in July and one in January convert differently in a
+ * zone that observes DST.
+ */
+declare function toDateTimeLocalInput(value: unknown): string;
+/** Wire value -> the `yyyy-MM-dd` a `date` input needs, in the viewer's zone. */
+declare function toDateInput(value: unknown): string;
+/**
+ * `yyyy-MM-ddTHH:mm` from the control -> a complete ISO-8601 string carrying the viewer's offset
+ * **for the entered date**.
+ *
+ * Building the `Date` from its parts rather than parsing the string is what makes this correct: it
+ * lets the browser apply its own timezone rules for that date, including DST. Using the *current*
+ * offset instead would be wrong for any value outside the present season -- entering a January date
+ * during summer would record an offset an hour off, and the stored instant would be an hour wrong.
+ *
+ * Across a DST discontinuity the browser resolves the wall clock itself, taking the offset in force
+ * before a fall-back and after a spring-forward. That is specified ECMAScript behaviour, and the
+ * server's conversion helper deliberately reproduces the same choice so the two cannot drift.
+ */
+declare function fromDateTimeLocalInput(local: unknown): string | null;
+/** `yyyy-MM-dd` from a `date` control -> an ISO string at local midnight with the viewer's offset. */
+declare function fromDateInput(local: unknown): string | null;
+/**
+ * Compares two wire timestamps **by instant**, which is what a `DateTimeOffset` means in Spark.
+ *
+ * Round-tripping a value through a date control legitimately rewrites its text -- a document holding
+ * `2026-12-31T23:59:00-08:00` comes back as `2027-01-01T08:59:00+01:00` from a viewer in Brussels --
+ * so a string comparison would mark every untouched date as edited and send a needless write on every
+ * save. Both of those name the same moment.
+ *
+ * Note this is the *opposite* of the trap on the server side, where `DateTimeOffset.Equals` compares
+ * the instant and silently hides a destroyed offset. Here comparing by instant is the correct thing:
+ * we are asking "did the user change this value", not "is the offset intact".
+ */
+declare function wireDatesEqual(a: unknown, b: unknown): boolean;
+/** True for the attribute data types that are edited through a native date/time control. */
+declare function isDateDataType(dataType: string | null | undefined): dataType is 'date' | 'datetime';
+/** Wire -> control, picking the right shape for the data type. */
+declare function toDateInputValue(dataType: string | null | undefined, value: unknown): string;
+/** Control -> wire, picking the right shape for the data type. */
+declare function fromDateInputValue(dataType: string | null | undefined, value: unknown): string | null;
+
 /**
  * Resolves an `EntityType` by its CLR type name (e.g. `"HR.Entities.Address"`).
  * Callers typically close over a list they already hold. `getEntityTypes()` is NOT cached --
@@ -612,6 +703,22 @@ declare function resolvedBreadcrumb(value: unknown, typeName?: string): string |
  * reference-query options page. Prefixed to avoid colliding with a real attribute name.
  */
 declare const AS_DETAIL_BREADCRUMBS_KEY = "__sparkBreadcrumbs";
+/**
+ * Reserved key under which a flattened row keeps the **wire** values of its date cells, keyed by
+ * attribute name.
+ *
+ * A date cell is edited through a native control that speaks only a bare local wall clock, so
+ * flattening converts the stored instant into the viewer's zone and saving converts it back. That
+ * round trip preserves the instant but necessarily rewrites the **offset** to the viewer's. For a
+ * cell the user actually edited that is correct — the offset is not business data. For one nobody
+ * touched it is pure loss: merely opening a row and saving would relabel a Seattle timestamp as a
+ * Brussels one.
+ *
+ * Keeping the original lets {@link dictToNestedPo} send back exactly what it was given whenever the
+ * instant is unchanged. Safe to carry for the same reason as the other reserved keys: the rebuild
+ * walks the entity type's attributes, never the dict's keys.
+ */
+declare const AS_DETAIL_ORIGINAL_DATES_KEY = "__sparkOriginalDates";
 /**
  * Whether a flattened-row key is one this module reserved rather than a model attribute.
  *
@@ -774,5 +881,5 @@ interface EvaluableAttribute {
  */
 declare function evaluateRules(attr: EvaluableAttribute, value: any): RuleFailure[];
 
-export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_ROW_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, hasShowedOnFlag, isPersistentObject, isQueryRow, isReservedAsDetailKey, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, resolveTranslation, resolvedBreadcrumb, selectionModeFor, selfBreadcrumb, valueFor };
+export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_ORIGINAL_DATES_KEY, AS_DETAIL_ROW_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, fromDateInput, fromDateInputValue, fromDateTimeLocalInput, hasShowedOnFlag, isDateDataType, isPersistentObject, isQueryRow, isReservedAsDetailKey, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, parseWireDate, resolveTranslation, resolvedBreadcrumb, selectionModeFor, selfBreadcrumb, toDateInput, toDateInputValue, toDateTimeLocalInput, valueFor, wireDatesEqual };
 export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryColumn, QueryResult, QueryResultItem, QueryResultItemValue, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkCellColumn, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkRow, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };

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

@@ -21,6 +21,29 @@ declare class InputTypePipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<InputTypePipe, "inputType", true>;
 }
 
+/**
+ * Parses a wire value into a `Date`, or `null` when it is absent or unparseable.
+ *
+ * Exists so the detail page and the grid agree. The grid gets its `Date` from `queryCellValue`, which
+ * needs a cell and a column and so cannot be reused on a detail attribute; before this, the detail page
+ * had no parsing step at all and printed the raw ISO string — `2026-12-31T23:59:00-08:00` in a
+ * definition list, while the grid showed `01/01/2027, 08:59` for the same document.
+ *
+ * The parsing contract is deliberately identical to `queryCellValue`'s: `new Date(...)`, and an
+ * unparseable value yields `null` so the caller can fall back to its own text rather than rendering
+ * "Invalid Date".
+ *
+ * Note what `new Date(...)` does to an offset, because it is the whole reason this is a separate step:
+ * it collapses the value to an instant and forgets the offset it was written with. That is correct for
+ * display — a viewer wants the moment in their own zone — but it means a `Date` can never be the thing
+ * you reach for when you need the *originating* wall clock. Read that from the wire value instead.
+ */
+declare class ParsedDatePipe implements PipeTransform {
+    transform(value: unknown): Date | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ParsedDatePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<ParsedDatePipe, "parsedDate", true>;
+}
+
 declare class AttributeValuePipe implements PipeTransform {
     transform(attrName: string, item: PersistentObject | null, entityType: EntityType | null, lookupRefOptions: Record<string, LookupReference>, allEntityTypes: EntityType[]): any;
     private formatAsDetailValue;
@@ -265,5 +288,5 @@ declare class QueryReferenceChipsPipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<QueryReferenceChipsPipe, "queryReferenceChips", true>;
 }
 
-export { ArrayValuePipe, AsDetailCellValuePipe, AsDetailColumnsPipe, AsDetailDisplayValuePipe, AsDetailTypePipe, AttributeValuePipe, CanCreateDetailRowPipe, CanDeleteDetailRowPipe, CanEditDetailRowPipe, ErrorForAttributePipe, IconNamePipe, InlineRefOptionsPipe, InputTypePipe, LookupDisplayTypePipe, LookupDisplayValuePipe, LookupOptionsPipe, QueryCellValuePipe, QueryReferenceChipsPipe, RawAttributeValuePipe, ReferenceAttrValuePipe, ReferenceChipsPipe, ReferenceDisplayValuePipe, ReferenceLinkRoutePipe, ResolveTranslationPipe, RouterLinkPipe, TranslateKeyPipe };
+export { ArrayValuePipe, AsDetailCellValuePipe, AsDetailColumnsPipe, AsDetailDisplayValuePipe, AsDetailTypePipe, AttributeValuePipe, CanCreateDetailRowPipe, CanDeleteDetailRowPipe, CanEditDetailRowPipe, ErrorForAttributePipe, IconNamePipe, InlineRefOptionsPipe, InputTypePipe, LookupDisplayTypePipe, LookupDisplayValuePipe, LookupOptionsPipe, ParsedDatePipe, QueryCellValuePipe, QueryReferenceChipsPipe, RawAttributeValuePipe, ReferenceAttrValuePipe, ReferenceChipsPipe, ReferenceDisplayValuePipe, ReferenceLinkRoutePipe, ResolveTranslationPipe, RouterLinkPipe, TranslateKeyPipe };
 export type { AsDetailCellValue, ReferenceChip };

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

@@ -1,5 +1,5 @@
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { PersistentObject, EntityType, ValidationError } from '@mintplayer/ng-spark/models';
+import { PersistentObject, EntityType, RefreshOverlay, ValidationError } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
 
@@ -13,6 +13,8 @@ declare class SparkPoCreateComponent {
     entityType: _angular_core.WritableSignal<EntityType | null>;
     type: _angular_core.WritableSignal<string>;
     formData: _angular_core.WritableSignal<Record<string, any>>;
+    /** Bound two-way to the form. See {@link getEditableAttributes}. */
+    refreshOverlay: _angular_core.WritableSignal<RefreshOverlay>;
     validationErrors: _angular_core.WritableSignal<ValidationError[]>;
     isSaving: _angular_core.WritableSignal<boolean>;
     private allEntityTypes;
@@ -20,6 +22,11 @@ declare class SparkPoCreateComponent {
     constructor();
     private onParamsChange;
     initFormData(): void;
+    /**
+     * ⚠️ Overlaid before filtering — same reason as <c>spark-po-edit</c>, and worse here: this list is
+     * the <em>only</em> source of the create payload, so an attribute a refresh hook revealed was not
+     * merely sent stale, it was absent from the new object entirely.
+     */
     getEditableAttributes(): _mintplayer_ng_spark_models.EntityAttributeDefinition[];
     onSave(): Promise<void>;
     onCancel(): void;

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

@@ -1,5 +1,5 @@
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { PersistentObject, EntityType, ValidationError } from '@mintplayer/ng-spark/models';
+import { PersistentObject, EntityType, RefreshOverlay, ValidationError } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
 
@@ -7,6 +7,7 @@ declare class SparkPoEditComponent {
     private readonly route;
     private readonly router;
     private readonly sparkService;
+    private readonly language;
     saved: _angular_core.OutputEmitterRef<PersistentObject>;
     cancelled: _angular_core.OutputEmitterRef<void>;
     colors: typeof Color;
@@ -15,6 +16,11 @@ declare class SparkPoEditComponent {
     type: string;
     id: string;
     formData: _angular_core.WritableSignal<Record<string, any>>;
+    /**
+     * Bound two-way to the form, which is where refreshes land. Read by
+     * {@link getEditableAttributes} so the save sees the object the user was actually shown.
+     */
+    refreshOverlay: _angular_core.WritableSignal<RefreshOverlay>;
     validationErrors: _angular_core.WritableSignal<ValidationError[]>;
     isSaving: _angular_core.WritableSignal<boolean>;
     private allEntityTypes;
@@ -23,6 +29,16 @@ declare class SparkPoEditComponent {
     private onParamsChange;
     initFormData(): void;
     private resolveEntityType;
+    /**
+     * The attributes this page will read values from when it builds the save.
+     *
+     * ⚠️ <b>Overlaid before filtering, not after loading.</b> A refresh hook can reveal an attribute
+     * that was hidden when the object was loaded, and the ordinary reason it does so is that the
+     * attribute has just become required. Filtering on the loaded state left such an attribute out of
+     * both {@link initFormData} and the save payload, so the user filled in a field whose value was
+     * then dropped on the floor and refused by the server as missing — with no way out of the form.
+     * The overlay is the form's, bound two-way, so the two halves cannot drift again.
+     */
     getEditableAttributes(): _mintplayer_ng_spark_models.EntityAttributeDefinition[];
     onSave(): Promise<void>;
     onCancel(): void;

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

@@ -83,8 +83,17 @@ declare class SparkPoFormComponent {
      * `entityType` identity and `SparkService` caches nothing, so re-setting it would re-issue every
      * reference query and lookup fetch on every refresh; mutating it in place would not re-render at
      * all.
+     *
+     * ⚠️ A `model`, not a plain signal, because the page that owns the save has to see it. This form
+     * renders from the overlaid attribute list; `spark-po-edit` and `spark-po-create` build the
+     * payload from their own copy of the same filter. While the overlay stopped here, those two
+     * filtered on the attribute's state *as loaded* — so an attribute a refresh hook revealed was
+     * rendered, filled in by the user, and then silently left out of the save. When the same hook also
+     * made it required (the ordinary case — a field appears *because* it is now needed) the server
+     * refused the save for the very field the user had just filled, and the form became a dead end
+     * with no way forward from inside it.
      */
-    refreshOverlay: _angular_core.WritableSignal<RefreshOverlay>;
+    refreshOverlay: _angular_core.ModelSignal<RefreshOverlay>;
     isRefreshing: _angular_core.WritableSignal<boolean>;
     colors: typeof Color;
     referenceOptions: _angular_core.WritableSignal<Record<string, QueryResultItem[]>>;
@@ -97,6 +106,21 @@ declare class SparkPoFormComponent {
     showAsDetailModal: _angular_core.WritableSignal<boolean>;
     editingArrayIndex: _angular_core.WritableSignal<number | null>;
     asDetailPermissions: _angular_core.WritableSignal<Record<string, EntityPermissions>>;
+    /**
+     * What the server said when it refused to construct or release a row.
+     *
+     * A local signal rather than the `validationErrors` input, because this is the one class of error
+     * the form raises on its own behalf: `validationErrors` is owned by the host (po-edit / po-create)
+     * and arrives from a save. Cleared at the start of each lifecycle call, so a stale refusal never
+     * outlives the click that caused it.
+     *
+     * Keyed by attribute name so a message renders against the grid it came from. A single global
+     * alert would have been less code and worse: a form with two detail grids would show one grid's
+     * refusal above the other, and the user's next click is on the grid, not the top of the page.
+     */
+    rowLifecycleErrors: _angular_core.WritableSignal<Record<string, ValidationError[]>>;
+    /** The refusal to render under `attrName`'s grid, if any. */
+    rowLifecycleErrorsFor(attrName: string): ValidationError[];
     asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, QueryResultItem[]>>>;
     ELookupDisplayType: typeof ELookupDisplayType;
     EReferenceDisplayType: typeof EReferenceDisplayType;
@@ -204,13 +228,57 @@ declare class SparkPoFormComponent {
     openAsDetailEditor(attr: EntityAttributeDefinition): void;
     saveAsDetailObject(): void;
     closeAsDetailModal(): void;
-    addInlineRow(attr: EntityAttributeDefinition): void;
-    addArrayItem(attr: EntityAttributeDefinition): void;
+    /**
+     * Whether `attr`'s row type asks the server before a row is added or removed.
+     *
+     * Read off the ROW type, never the parent. `asDetailTypes` already resolves it from the Query-gated
+     * catalogue first and the parent's `detailTypes` second, and the flag survives the server-side
+     * pruning of the embedded copy, so both sources give the same answer.
+     */
+    private roundTripsRowLifecycle;
+    /** The type id to address the row type by on the wire. */
+    private rowTypeId;
+    /**
+     * How to name the PARENT's type on the wire.
+     *
+     * ⚠️ The fallback must be the type **id**, never `clrType`. The server resolves this through
+     * `ModelLoader.ResolveEntityType`, which accepts a GUID or a declared alias and nothing else — so
+     * a CLR name resolves to null and the request is refused, indistinguishably from an unknown type.
+     * The user would see "the server refused this change" on a perfectly ordinary Add.
+     *
+     * It is a live path, not a theoretical one: `spark-po-create` binds no `parentType` (there is no
+     * parent route segment on a create page), so every host that creates an object with an opted-in
+     * detail grid lands here.
+     */
+    private parentTypeForWire;
+    /**
+     * Builds the dict a new row starts from: `{}` as before, or the object the server constructed.
+     *
+     * Returns null when the server refused — the caller must then add nothing, which is the whole
+     * difference between a veto and a message.
+     */
+    private buildNewRow;
+    /**
+     * Asks whether a stored row may be removed. True when it may — including every case where there
+     * is nothing to ask about: a type that has not opted in, a parent that has never been saved, or a
+     * row with no key yet because it was added in this same editing session and never persisted.
+     */
+    private mayRemoveRow;
+    /**
+     * Turns a rejected lifecycle call into something the user can read.
+     *
+     * The envelope puts validation errors under `result`, the same place the save path reads them
+     * from — reading `error.error.errors` matched nothing and made every veto silent.
+     */
+    private clearRowLifecycleError;
+    private captureRowLifecycleError;
+    addInlineRow(attr: EntityAttributeDefinition): Promise<void>;
+    addArrayItem(attr: EntityAttributeDefinition): Promise<void>;
     editArrayItem(attr: EntityAttributeDefinition, index: number): void;
-    removeArrayItem(attr: EntityAttributeDefinition, index: number): void;
+    removeArrayItem(attr: EntityAttributeDefinition, index: number): Promise<void>;
     onAsDetailReorder(attr: EntityAttributeDefinition, event: CdkDragDrop<Record<string, any>[]>): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkPoFormComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkPoFormComponent, "spark-po-form", never, { "entityType": { "alias": "entityType"; "required": false; "isSignal": true; }; "formData": { "alias": "formData"; "required": false; "isSignal": true; }; "validationErrors": { "alias": "validationErrors"; "required": false; "isSignal": true; }; "showButtons": { "alias": "showButtons"; "required": false; "isSignal": true; }; "isSaving": { "alias": "isSaving"; "required": false; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "objectTypeId": { "alias": "objectTypeId"; "required": false; "isSignal": true; }; "objectId": { "alias": "objectId"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkPoFormComponent, "spark-po-form", never, { "entityType": { "alias": "entityType"; "required": false; "isSignal": true; }; "formData": { "alias": "formData"; "required": false; "isSignal": true; }; "validationErrors": { "alias": "validationErrors"; "required": false; "isSignal": true; }; "showButtons": { "alias": "showButtons"; "required": false; "isSignal": true; }; "isSaving": { "alias": "isSaving"; "required": false; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "objectTypeId": { "alias": "objectTypeId"; "required": false; "isSignal": true; }; "objectId": { "alias": "objectId"; "required": false; "isSignal": true; }; "refreshOverlay": { "alias": "refreshOverlay"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; "refreshOverlay": "refreshOverlayChange"; }, never, never, true, never>;
 }
 
 /**

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

@@ -3,6 +3,7 @@ import { RetryActionPayload, RetryActionResult, TranslatedString, StreamingMessa
 import { Observable } from 'rxjs';
 import { SortColumn } from '@mintplayer/pagination';
 import { SafeHtml } from '@angular/platform-browser';
+import { HttpInterceptorFn, HttpFeature, HttpFeatureKind } from '@angular/common/http';
 
 declare class RetryActionService {
     private resolveRetry;
@@ -41,12 +42,44 @@ declare class SparkStreamingService {
     static ɵprov: i0.ɵɵInjectableDeclaration<SparkStreamingService>;
 }
 
+/**
+ * Context for {@link SparkService.newObject}. Everything is optional: a standalone New sends an
+ * empty body, and an AsDetail row on a parent that has never been saved sends no `parentId` —
+ * which is the honest answer, not a gap. The server hands the hook a null parent rather than
+ * trusting the client's copy of one.
+ */
+interface NewObjectOptions {
+    /** Name of the parent's AsDetail attribute the row is for; absent for a standalone New. */
+    asDetailAttribute?: string;
+    /** The parent's entity type — required whenever `asDetailAttribute` is set. */
+    parentType?: string;
+    /** The parent's id, absent while the parent is itself unsaved. */
+    parentId?: string;
+    /** Free-form arguments, e.g. which variant a New menu chose. */
+    parameters?: Record<string, string>;
+}
+/** Context for {@link SparkService.deleteRow}. Every field is required — see `DeleteRow.cs`. */
+interface DeleteRowOptions {
+    asDetailAttribute: string;
+    parentType: string;
+    parentId: string;
+    /** The row's `__sparkRowKey`, as it arrived from the server. */
+    rowKey: string;
+    parameters?: Record<string, string>;
+}
 declare class SparkService {
     #private;
     private readonly config;
     private readonly baseUrl;
     private readonly http;
     private readonly retryActionService;
+    /**
+     * How many prompts one request will answer before giving up. Matches the .NET client's
+     * `SparkClient.MaxRetryDepth`, and for the same reason: this is a termination bound, not a
+     * capacity one. Far above any real conversation (Fleet's longest is two) and far below anything
+     * that could hide a spin.
+     */
+    private static readonly MAX_RETRY_DEPTH;
     private readonly dispatcher;
     getEntityTypes(): Promise<EntityType[]>;
     getEntityType(id: string): Promise<EntityType>;
@@ -101,6 +134,31 @@ declare class SparkService {
      * path form the inline validation errors use — `Jobs[2].ProfessionId`.
      */
     refresh(type: string, data: Partial<PersistentObject>, triggeredBy: string): Promise<PersistentObject>;
+    /**
+     * Asks the server to construct a new object of `type`, so `OnNewAsync` can default it.
+     *
+     * Writes nothing — the object comes back unsaved, and for an AsDetail row the parent still owns
+     * the save. Only called for a row type whose `serverSideRowLifecycle` is on; every other type
+     * keeps building its blank row locally, which is why switching the flag off costs no request.
+     *
+     * ⚠️ The row comes back **keyed**: the server constructs the CLR instance, so the row-key field
+     * initializer runs and `po.id` carries the key. Flattening it with `nestedPoToDict` therefore
+     * populates `__sparkRowKey`, and the row is matchable on save from the moment it is added — the
+     * whole reason this round-trip is worth a request.
+     */
+    newObject(type: string, options?: NewObjectOptions): Promise<PersistentObject>;
+    /**
+     * Asks whether a stored row may leave its parent's AsDetail collection.
+     *
+     * Deletes nothing: a resolved promise means the caller may splice the row out of the collection
+     * it is editing, and the removal is persisted with the parent. A hook that refuses rejects with a
+     * 400 whose `error.error.result.errors` carries the readable reason, exactly like a save.
+     *
+     * A POST — as everything is now. It used to be worth explaining: the framework's real delete route
+     * was a catch-all that would have swallowed a sibling DELETE. The catch-all is gone with the rest
+     * of the route variables.
+     */
+    deleteRow(type: string, options: DeleteRowOptions): Promise<void>;
     delete(type: string, id: string): Promise<void>;
     getCustomActions(objectTypeId: string): Promise<CustomActionDefinition[]>;
     /**
@@ -123,8 +181,16 @@ declare class SparkService {
     updateLookupReferenceValue(name: string, key: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
     deleteLookupReferenceValue(name: string, key: string): Promise<void>;
     private postWithEnvelope;
-    private putWithEnvelope;
-    private deleteWithEnvelope;
+    /**
+     * A read: posts the request, and returns the response **as-is** rather than unwrapping an
+     * envelope.
+     *
+     * The read endpoints moved from GET to POST so their hooks could prompt, but their success
+     * responses are still bare — a `PersistentObject`, a `QueryResult`. Only the 449 is enveloped,
+     * because a retry has nowhere else to live. So this shares the retry loop with the mutating calls
+     * and nothing else.
+     */
+    private sendRead;
     private sendWithEnvelope;
     private handleEnvelopeRetryError;
     static ɵfac: i0.ɵɵFactoryDeclaration<SparkService, never>;
@@ -222,4 +288,35 @@ declare class SparkQueryActionsService {
     static ɵprov: i0.ɵɵInjectableDeclaration<SparkQueryActionsService>;
 }
 
-export { RetryActionService, SparkIconRegistry, SparkLanguageService, SparkQueryActionsService, SparkService, SparkStreamingService };
+/**
+ * The header carrying the viewer's IANA timezone id, e.g. `Europe/Brussels`.
+ * Must stay in lockstep with `RequestTimeZoneResolver.HeaderName` on the server.
+ */
+declare const SPARK_TIMEZONE_HEADER = "X-Spark-Timezone";
+/**
+ * Returns the browser's IANA zone id, or `null` when the environment cannot name one.
+ *
+ * An id is deliberately sent rather than a numeric offset: an offset is only valid at one instant,
+ * so a server asked to render "next Tuesday at 09:00" from an offset captured today gets it wrong
+ * across a DST boundary. A zone id carries the rules, not one sample of them.
+ */
+declare function resolveBrowserTimeZone(): string | null;
+/**
+ * Attaches {@link SPARK_TIMEZONE_HEADER} to same-origin requests.
+ *
+ * **This does not participate in reading or writing timestamps.** A `DateTimeOffset` means an
+ * instant, and the browser converts in both directions on those paths. The header exists for work
+ * the server starts on its own — a scheduled export, a notification email — where there is no
+ * browser in the loop to do the converting but the output still has to read as local time.
+ */
+declare const sparkTimezoneInterceptor: HttpInterceptorFn;
+/**
+ * `provideHttpClient(...withSparkTimezone())` — registers {@link sparkTimezoneInterceptor}.
+ *
+ * Spreadable alongside `withSparkAuth()`:
+ * `provideHttpClient(...withSparkAuth(), ...withSparkTimezone())`.
+ */
+declare function withSparkTimezone(): HttpFeature<HttpFeatureKind>[];
+
+export { RetryActionService, SPARK_TIMEZONE_HEADER, SparkIconRegistry, SparkLanguageService, SparkQueryActionsService, SparkService, SparkStreamingService, resolveBrowserTimeZone, sparkTimezoneInterceptor, withSparkTimezone };
+export type { DeleteRowOptions, NewObjectOptions };