@mintplayer/ng-spark 22.23.0 → 22.25.0

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

@@ -1,65 +1,368 @@
-import * as _mintplayer_ng_spark_models 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';
-
-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;
-    entityType: _angular_core.WritableSignal<EntityType | null>;
-    item: _angular_core.WritableSignal<PersistentObject | null>;
-    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;
-    generalErrors: _angular_core.Signal<ValidationError[]>;
-    constructor();
-    private onParamsChange;
-    initFormData(): void;
-    /**
-     * Resolves a nested AsDetail type by CLR name, for rebuilding the nested PO wire shape on save.
-     *
-     * ⚠️ <b>`detailTypes` first, catalogue second.</b> The catalogue from `/spark/types` is
-     * <b>Query-gated</b>, and an AsDetail row type usually has no rights of its own — nobody grants
-     * `Query/GateSettings`, because a gate is edited through the Repository that owns it. So the
-     * catalogue does not contain it, the resolver returned undefined, and the save quietly took the
-     * scalar branch: the attribute went out as a raw dict under `value` instead of a nested PO under
-     * `object`, the server could not map it, and `EntityMapper`'s conversion `catch` swallowed the
-     * failure. The save reported success and wrote nothing.
-     * <para>
-     * `detailTypes` is the parent's own copy of its row types, carried on the type definition for
-     * exactly this reason (#385 fixed the rendering half; this is the save half). It is gated on the
-     * parent's right, which is the right that governs editing the row anyway.
-     * </para>
-     */
-    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;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkPoEditComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkPoEditComponent, "spark-po-edit", never, {}, { "saved": "saved"; "cancelled": "cancelled"; }, never, never, true, never>;
+import { Color } from "@mintplayer/ng-bootstrap";
+import { EntityAttributeDefinition, EntityType, EntityTypeResolver, PersistentObject, QueryColumn, QueryResultItem, RefreshOverlay, ValidationError } from "@mintplayer/ng-spark/models";
+import * as i0 from "@angular/core";
+import { ReferenceChip } from "@mintplayer/ng-spark/pipes";
+/**
+ * Three-way merge of an edit form after a 409 (contributions PRD §5, Q10).
+ *
+ * The three sides are all in the form's own flat-dict shape (`nestedPoToDict`): **base** is the
+ * object as this page loaded it, **mine** is the form now, **theirs** is the object re-fetched after
+ * the server refused the save. Comparing in the form's shape rather than on the wire matters: the
+ * form coerces while it loads (an unset string becomes `''`, a date becomes a wall clock), so a
+ * wire-shaped base would report every such field as "changed by me" and turn an edit the other
+ * user made to it into a false conflict. All three sides go through the same flattening, so only
+ * real edits differ.
+ *
+ * Pure: no Angular, no I/O. Values are compared with `formValuesEqual`, which ignores the per-read
+ * fields a flattened row carries (row key, breadcrumb, original dates).
+ */
+/** Which side a conflict is resolved to. */
+export type ConflictSide = 'mine' | 'theirs';
+export interface MergeSchema {
+  /** The attributes being merged: the ones the form edits. */
+  attributes: EntityAttributeDefinition[];
+  /** Resolves AsDetail row types by CLR name, to merge rows per attribute. */
+  resolve: EntityTypeResolver;
 }
-
-export { SparkPoEditComponent };
+export interface MergeConflict {
+  /**
+   * Where the conflict sits, and the key its choice is given under: `Title`, `Address.Street`,
+   * `Lyrics[ko/Kore]` for a whole row, `Lyrics[ko/Kore].Text` for one attribute of a row.
+   */
+  path: string;
+  /** `value`: both sides changed one attribute differently. `row`: a row keep/remove or add/add clash. */
+  kind: 'value' | 'row';
+  /** The attribute the values belong to — for a row conflict, the AsDetail list attribute. */
+  attribute: EntityAttributeDefinition;
+  /** The top-level attribute this sits under (the attribute itself at the root). */
+  rootAttribute: EntityAttributeDefinition;
+  /** The path of the object this sits in: `''` at the root, `Lyrics[ko/Kore]` inside a row. */
+  group: string;
+  /** A readable name for the row this sits in, when it is inside one. */
+  rowLabel?: string;
+  /**
+   * For a row conflict, or a value conflict on an embedded (AsDetail) object: the row type's
+   * attributes, so the values can be shown cell by cell. Absent when the row type did not resolve.
+   */
+  rowAttributes?: EntityAttributeDefinition[];
+  /** The row type's name, to filter the server's type-name breadcrumb placeholder. */
+  rowTypeName?: string;
+  /** The values, in the form's shape. For a row conflict, the row dict, or `undefined` when absent. */
+  base: unknown;
+  mine: unknown;
+  theirs: unknown;
+}
+/** Something the other side changed that the merge took over. */
+export interface TheirChange {
+  path: string;
+  attribute: EntityAttributeDefinition;
+  rootAttribute: EntityAttributeDefinition;
+}
+export interface MergeResult {
+  /** The form values to continue editing with. Unresolved conflicts hold THEIR value. */
+  merged: Record<string, any>;
+  /** Only true conflicts: both sides changed the same thing to different content. */
+  conflicts: MergeConflict[];
+  /** What the other side changed that was taken over without a conflict. */
+  theirChanges: TheirChange[];
+  /**
+   * Contribution rows (a `[Contribution]` property, contributions M5b) that I changed but that another
+   * contributor changed too: theirs won, my edit of them was dropped — say so.
+   */
+  contributionNotices: ContributionNotice[];
+}
+/** A contribution row taken from theirs over my own edit, because another contributor wrote it. */
+export interface ContributionNotice {
+  /** `Lyrics[en/Latn]`. */
+  path: string;
+  /** The list attribute. */
+  attribute: EntityAttributeDefinition;
+  /** A readable name for the row (its breadcrumb, else its key). */
+  rowLabel: string;
+}
+/** The key under which the server marks a contribution row (`metadata.contribution`). */
+export declare const CONTRIBUTION_ROW_METADATA = "contribution";
+/**
+ * Whether a flattened row is a contribution row whose shown version the caller wrote: `true` / `false`
+ * for a contribution row, `undefined` for any other row (the server marks contribution rows on load).
+ */
+export declare function contributionRowIsOwn(row: Record<string, any> | undefined): boolean | undefined;
+/**
+ * Merges `mine` onto `theirs` against `base`.
+ *
+ * - An attribute changed only by me keeps mine; changed only by them takes theirs; changed by both
+ *   to the same content is no conflict; changed by both differently is a conflict.
+ * - A read-only attribute always takes theirs, silently: the user cannot have edited it.
+ * - AsDetail lists are matched per row by the row key (`[ValueKey]`). A row added, removed or changed
+ *   on one side only comes from that side. The same key added on both sides with different content,
+ *   or a row removed on one side and edited on the other, is a row conflict. A row changed on both
+ *   sides is merged per attribute. The order is theirs, then the rows only I have.
+ *
+ * `choices` resolves conflicts by path; a conflict without a choice resolves to theirs. Run it once
+ * without choices to find the conflicts, and again with the user's choices to build the result —
+ * the conflicts reported do not depend on the choices.
+ */
+export declare function mergeThreeWay(base: Record<string, any>, mine: Record<string, any>, theirs: Record<string, any>, schema: MergeSchema, choices?: Readonly<Record<string, ConflictSide>>): MergeResult;
+/**
+ * Reference labels by referenced id, for rendering a Reference in the conflict dialog.
+ *
+ * The form keeps only a reference's id (`nestedPoToDict` drops the breadcrumbs), so a conflict value
+ * on its own renders as the raw id. The labels live elsewhere: on the objects as read — the object as
+ * loaded and the re-fetched one each carry the server-resolved breadcrumb of every reference they
+ * hold, rows included — and, for a reference the user just picked, in the candidate list the picker
+ * chose it from (a picker only ever selects from those options). Ids are document ids, unique across
+ * collections, so one flat map serves every attribute and every row.
+ */
+export type ReferenceLabels = Record<string, string>;
+/** Adds the labels of every reference in `po` (recursing into AsDetail rows). The first label for an id wins. */
+export declare function addReferenceLabelsOf(po: PersistentObject | null | undefined, into: ReferenceLabels): ReferenceLabels;
+/** Adds the labels of reference candidates (`QueryResultItem.breadcrumb` by `id`). The first label for an id wins. */
+export declare function addReferenceLabelsOfOptions(options: Iterable<readonly QueryResultItem[] | undefined>, into: ReferenceLabels): ReferenceLabels;
+/** A 409 whose merge found true conflicts: everything needed to re-run it with the user's choices. */
+interface PendingConflict {
+  /** The object as loaded, for its reference labels. */
+  loaded: PersistentObject;
+  theirs: PersistentObject;
+  base: Record<string, any>;
+  mine: Record<string, any>;
+  theirsForm: Record<string, any>;
+  schema: MergeSchema;
+  result: MergeResult;
+}
+export declare class SparkPoEditComponent {
+  private readonly route;
+  private readonly router;
+  private readonly sparkService;
+  private readonly language;
+  /** `SparkConfig.conflictDialog.showChangedBy`: whether the conflict notice may name a user at all. */
+  private readonly showChangedBy;
+  saved: import("@angular/core").OutputEmitterRef<PersistentObject>;
+  cancelled: import("@angular/core").OutputEmitterRef<void>;
+  colors: typeof Color;
+  entityType: import("@angular/core").WritableSignal<EntityType | null>;
+  item: import("@angular/core").WritableSignal<PersistentObject | null>;
+  /**
+   * The type as this form edits it: the loaded object can be stricter than the type, because a
+   * server hook may mark an attribute read-only for this row and this caller (QnA: a translator who
+   * is not the question's author edits only its translations; the server drops the rest from the
+   * save anyway). Shared by the form and {@link getEditableAttributes}, so what is drawn, what is
+   * initialised and what is saved agree. A refresh overlay can still lift it.
+   */
+  formEntityType: import("@angular/core").Signal<EntityType | null>;
+  type: string;
+  id: string;
+  formData: import("@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: import("@angular/core").WritableSignal<RefreshOverlay>;
+  validationErrors: import("@angular/core").WritableSignal<ValidationError[]>;
+  isSaving: import("@angular/core").WritableSignal<boolean>;
+  private allEntityTypes;
+  generalErrors: import("@angular/core").Signal<ValidationError[]>;
+  /** After a 409 was merged: what they changed, and that nothing has been saved yet. */
+  private readonly conflictNoticeText;
+  /** The notice with its "Changed by X at T", which fills in the name once History resolved it. */
+  readonly conflictNotice: import("@angular/core").Signal<string | null>;
+  /** A 409 whose merge has true conflicts, waiting on the dialog. */
+  pendingConflict: import("@angular/core").WritableSignal<PendingConflict | null>;
+  protected readonly pendingConflicts: import("@angular/core").Signal<import("@mintplayer/ng-spark/po-edit").MergeConflict[]>;
+  /**
+   * The name History resolved for whoever wrote the version with `etag`, or null. Only ever set from
+   * the revision list, so it is there only when `SparkConfig.conflictDialog.showChangedBy` is true and
+   * the caller holds `History/T` (see {@link lookUpChangedBy}).
+   */
+  private readonly changedByName;
+  private readonly form;
+  private readonly locale;
+  constructor();
+  private onParamsChange;
+  initFormData(): void;
+  /**
+   * The form's flat-dict shape of `currentItem`. Also how a conflict merge brings the object as
+   * loaded and as re-fetched into the form's shape, so all three sides went through the same
+   * coercions and only real edits differ.
+   */
+  private formDataFrom;
+  /**
+   * Resolves a nested AsDetail type by CLR name, for rebuilding the nested PO wire shape on save.
+   *
+   * ⚠️ <b>`detailTypes` first, catalogue second.</b> The catalogue from `/spark/types` is
+   * <b>Query-gated</b>, and an AsDetail row type usually has no rights of its own — nobody grants
+   * `Query/GateSettings`, because a gate is edited through the Repository that owns it. So the
+   * catalogue does not contain it, the resolver returned undefined, and the save quietly took the
+   * scalar branch: the attribute went out as a raw dict under `value` instead of a nested PO under
+   * `object`, the server could not map it, and `EntityMapper`'s conversion `catch` swallowed the
+   * failure. The save reported success and wrote nothing.
+   * <para>
+   * `detailTypes` is the parent's own copy of its row types, carried on the type definition for
+   * exactly this reason (#385 fixed the rendering half; this is the save half). It is gated on the
+   * parent's right, which is the right that governs editing the row anyway.
+   * </para>
+   */
+  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(): import("@mintplayer/ng-spark/models").EntityAttributeDefinition[];
+  onSave(): Promise<void>;
+  onCancel(): void;
+  /**
+   * After a 409: re-fetch the object (a normal read, so read rights and row security apply) and
+   * merge this form onto it, three-way against the object as loaded (contributions PRD §5, Q10).
+   * Disjoint edits merge silently and the page says what they changed; true conflicts open the
+   * dialog. Either way the form is rebased onto the fresh etag and **nothing is saved** — the user
+   * reviews and saves, and the server's validation and business rules run again on the result.
+   */
+  private resolveConcurrencyConflict;
+  /**
+   * Reference labels for the dialog, by id. The form keeps only ids; the labels are on the two reads
+   * (theirs first: it is the fresher) and, for a reference the user just picked, in the candidate
+   * lists the form's pickers choose from — top-level and per AsDetail column.
+   */
+  protected readonly conflictReferenceLabels: import("@angular/core").Signal<ReferenceLabels>;
+  /**
+   * Resolves who wrote their version to a display name, through History: the newest revision from
+   * `POST /spark/po/revisions` (page size 1) carries the name the app's `IHistoryUserNameResolver`
+   * gave it. Taken only when that revision is the version the merge ran against, and — when the
+   * object has `ModifiedBy` — written by that same user.
+   *
+   * Rights: asked only with `History/T` (the endpoint refuses anyone else anyway), so a caller who may
+   * not read the history never sees a name from it. Without History installed, or on any failure,
+   * nothing is set and the line names no user. Called only when `SparkConfig.conflictDialog.showChangedBy`
+   * is true.
+   */
+  private lookUpChangedBy;
+  /** The dialog's choices, applied on top of the merge. */
+  onConflictResolved(choices: Record<string, ConflictSide>): void;
+  /** Closing the dialog changes nothing: the form keeps its values and the conflict message. */
+  onConflictCancelled(): void;
+  /**
+   * Makes `theirs` the object this page edits: its etag is what the next save sends, and it is the
+   * base a second conflict is merged against. `isValueChanged` is computed against it on save, so
+   * only what differs from their version is sent as changed.
+   */
+  private rebase;
+  /** The dialog's "they also changed" line, or null when the merge took nothing of theirs. */
+  protected readonly theyChanged: import("@angular/core").Signal<string | null>;
+  protected readonly conflictAudit: import("@angular/core").Signal<string | null>;
+  /**
+   * "Changed by X at T" for an `IAuditable` target. History stamps `ModifiedBy`/`ModifiedAt` on the
+   * entity, and they reach this page only when the model declares them as attributes. `ModifiedBy` is
+   * a user id (History stores ids, never names), and that id is never shown. X is the name History
+   * resolved for exactly this version ({@link lookUpChangedBy}), which is only looked up when
+   * `SparkConfig.conflictDialog.showChangedBy` is true; with no resolved name there is no user part.
+   * Either half is shown alone when only it is present, and nothing when neither is.
+   */
+  private auditLine;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkPoEditComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkPoEditComponent, "spark-po-edit", never, {}, {
+    "saved": "saved";
+    "cancelled": "cancelled";
+  }, never, never, true, never>;
+}
+/**
+ * One side of a conflict: ready for `<spark-grid-cell>`, or, for a whole row or embedded object, its
+ * attributes cell by cell (`fields`), or plain text (a removed row, or a value with no type to show).
+ */
+interface ConflictCell {
+  column: QueryColumn;
+  display: unknown;
+  rendererValue: unknown;
+  chips: ReferenceChip[];
+  item: PersistentObject;
+  text?: string;
+  fields?: ConflictField[];
+}
+/** One attribute of a row on one side, and whether the other side holds something else there. */
+interface ConflictField {
+  attribute: EntityAttributeDefinition;
+  cell: ConflictCell;
+  differs: boolean;
+}
+interface ConflictGroup {
+  key: string;
+  /** The root attribute and row this group sits in; empty for plain top-level attributes. */
+  attribute?: EntityAttributeDefinition;
+  rowLabel?: string;
+  entries: {
+    conflict: MergeConflict;
+    mine: ConflictCell;
+    theirs: ConflictCell;
+  }[];
+}
+/**
+ * The true conflicts of a three-way merge after a 409, Mine or Theirs per conflict (grouped by
+ * AsDetail row), rendered with the same `<spark-grid-cell>` a query grid and History use. It only
+ * collects choices: applying them, and rebasing onto the fresh etag, is the edit page's job — and
+ * nothing is saved from here.
+ */
+export declare class SparkPoConflictDialogComponent {
+  private readonly language;
+  private readonly gridRenderers;
+  /** The true conflicts; the dialog is open while there are any. */
+  conflicts: import("@angular/core").InputSignal<MergeConflict[]>;
+  /**
+   * Reference labels by id — the form keeps only ids. Built by the edit page from the object as
+   * loaded, the re-fetched one, and the form's reference candidates (see `reference-labels.ts`).
+   * An id without a label shows as the id.
+   */
+  referenceLabels: import("@angular/core").InputSignal<ReferenceLabels>;
+  /** "Changed by X at T", when the object is audited. */
+  audit: import("@angular/core").InputSignal<string | null>;
+  /** "They also changed: …", the changes merged without a conflict. */
+  theyChanged: import("@angular/core").InputSignal<string | null>;
+  resolved: import("@angular/core").OutputEmitterRef<Record<string, ConflictSide>>;
+  cancelled: import("@angular/core").OutputEmitterRef<void>;
+  colors: typeof Color;
+  protected readonly choices: import("@angular/core").WritableSignal<Record<string, ConflictSide>>;
+  private readonly lookupOptions;
+  protected readonly complete: import("@angular/core").Signal<boolean>;
+  protected readonly groups: import("@angular/core").Signal<ConflictGroup[]>;
+  constructor();
+  choose(path: string, side: ConflictSide): void;
+  chooseAll(side: ConflictSide): void;
+  apply(): void;
+  /**
+   * One side of a conflict. A whole row (or an embedded object, when its type resolved) is shown
+   * attribute by attribute with the same cells as a scalar, marking where `other` — the other side —
+   * holds something else; a row absent on this side is "(removed)", which is what choosing it means.
+   */
+  private sideCell;
+  /** One attribute's value, in the form's shape, as a `<spark-grid-cell>`. */
+  private cell;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkPoConflictDialogComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkPoConflictDialogComponent, "spark-po-conflict-dialog", never, {
+    "conflicts": {
+      "alias": "conflicts";
+      "required": false;
+      "isSignal": true;
+    };
+    "referenceLabels": {
+      "alias": "referenceLabels";
+      "required": false;
+      "isSignal": true;
+    };
+    "audit": {
+      "alias": "audit";
+      "required": false;
+      "isSignal": true;
+    };
+    "theyChanged": {
+      "alias": "theyChanged";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "resolved": "resolved";
+    "cancelled": "cancelled";
+  }, never, never, true, never>;
+}