@mintplayer/ng-spark 22.23.0 → 22.25.0

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

@@ -0,0 +1,231 @@
+import { EntityAttributeDefinition, PersistentObject, SparkQuery } from "@mintplayer/ng-spark/models";
+import * as i0 from "@angular/core";
+import { Provider } from "@angular/core";
+import { SparkService } from "@mintplayer/ng-spark/services";
+import { SparkDetailContext, SparkQueryRowAction } from "@mintplayer/ng-spark/panels";
+import { SparkAttributeRendererRegistration } from "@mintplayer/ng-spark/renderers";
+/** One line of a line diff: unchanged, only in the new text, or only in the old one. */
+export interface SparkDiffLine {
+  kind: 'same' | 'added' | 'removed';
+  text: string;
+}
+/** Splits a text into lines (`\r\n`, `\r` and `\n` alike); an empty or absent text has none. */
+export declare function splitLines(text: string | null | undefined): string[];
+/**
+ * A line diff of `newText` against `oldText`: the longest common subsequence of their lines kept as
+ * `same`, everything else `removed` (old) or `added` (new), in reading order — at a change, the old
+ * lines come before the new ones. Pure, no dependency.
+ *
+ * Beyond {@link MAX_CELLS} cells (thousands of lines on both sides) the common prefix and suffix are
+ * still matched, and the middle is reported as removed-then-added rather than building a huge table.
+ */
+export declare function lineDiff(oldText: string | null | undefined, newText: string | null | undefined): SparkDiffLine[];
+/** Whether a diff changes anything. */
+export declare function diffHasChanges(lines: readonly SparkDiffLine[]): boolean;
+/**
+ * Where the `lineDiff` renderer finds the text to compare with — its `rendererOptions`:
+ *
+ * - `compareType`: the model name (or alias, or id) of the object to load;
+ * - its id: `compareIdAttribute` (an attribute of this object holding it), or
+ *   `compareIdPattern` + `compareIdReplacement` (a regular expression and replacement applied to this
+ *   object's id);
+ * - `compareAttribute`: the attribute of that object holding the text — or, for an AsDetail list, the
+ *   list, with `compareRowKeyPattern` + `compareRowKeyReplacement` (deriving the row key from this
+ *   object's id) and `compareRowAttribute` (the text on the row); for a single AsDetail object,
+ *   `compareRowAttribute` alone.
+ *
+ * Contributions seeds these on a generated contribution type's text values, comparing against the
+ * target's row of the same slot (the current version).
+ */
+export interface SparkLineDiffSource {
+  type: string;
+  id: string;
+  attribute: string;
+  rowKey?: string;
+  rowAttribute?: string;
+}
+/** The comparison source for `item`, or null when the options do not describe one. */
+export declare function lineDiffSourceOf(options: Record<string, any> | null | undefined, item: PersistentObject | null | undefined): SparkLineDiffSource | null;
+/** The text at `source` in the loaded object, or null when it is not there (or not readable). */
+export declare function lineDiffTextOf(po: PersistentObject | null | undefined, source: SparkLineDiffSource): string | null;
+/**
+ * The generic `lineDiff` detail renderer: this attribute's text, diffed line by line against a text
+ * elsewhere ({@link SparkLineDiffSource}) — added lines marked `+`, removed ones `−`. When the other
+ * object cannot be read (no right, gone), the text is shown as it is, with a note.
+ *
+ * Register through `sparkContributionRenderers` (or on its own: `{ name: 'lineDiff', detailComponent:
+ * SparkLineDiffComponent }`).
+ */
+export declare class SparkLineDiffComponent {
+  private readonly spark;
+  value: import("@angular/core").InputSignal<any>;
+  attribute: import("@angular/core").InputSignal<EntityAttributeDefinition | undefined>;
+  options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  item: import("@angular/core").InputSignal<PersistentObject | undefined>;
+  protected readonly text: import("@angular/core").Signal<string>;
+  /** The compared text: undefined while loading, null when it could not be read. */
+  private readonly compared;
+  protected readonly state: import("@angular/core").Signal<"loading" | "diff" | "unavailable">;
+  protected readonly lines: import("@angular/core").Signal<SparkDiffLine[]>;
+  protected readonly changed: import("@angular/core").Signal<boolean>;
+  private generation;
+  constructor();
+  protected marker(line: SparkDiffLine): string;
+  private load;
+  /** The entity type id for a model name or alias (the load endpoint is keyed by the type's id). */
+  private typeIdOf;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkLineDiffComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkLineDiffComponent, "spark-line-diff", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "attribute": {
+      "alias": "attribute";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+    "item": {
+      "alias": "item";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** The `rendererOptions` Contributions writes on each attribution attribute (library README, "Client contract"). */
+export interface SparkContributionAttributionOptions {
+  /** The generated contributions query's alias (`songlyricscontributions`). */
+  contributionsQuery: string;
+  /** The target's model name: the query's `parentType` (`Song`). */
+  targetType: string;
+  /** The `[Contribution]` property (`Lyrics`). */
+  property: string;
+  /** The slot attributes, in id order: one column filter each (`Language`, `Script`). */
+  slots: string[];
+  /** The attribution attributes the row carries: `ContributorName`, `UpdatedAt`, `ContributionCount`. */
+  attribution: string[];
+}
+/** The History link of a row: `/query/{contributionsQuery}?parentId=…&parentType=…&{slot}=…`. */
+export interface SparkContributionHistoryLink {
+  commands: string[];
+  queryParams: Record<string, string>;
+}
+/** The History link for `row` of the object `ownerId`, or null when either is missing. */
+export declare function contributionHistoryLink(options: Partial<SparkContributionAttributionOptions> | null | undefined, row: Record<string, any> | null | undefined, ownerId: string | null | undefined): SparkContributionHistoryLink | null;
+/** "3 days ago" in `language`, from an ISO instant; null when it does not parse. */
+export declare function relativeTime(value: unknown, language: string, now?: number): string | null;
+/**
+ * The `contributionAttribution` AsDetail **row** renderer (contributions PRD Q6): one line under a
+ * row — "by Alice · 3 days ago · History (4)" — instead of three columns. Only the parts the
+ * declaration asked for (`rendererOptions.attribution`) and that the row has; History links to the
+ * slot's contributions query (`/query/{contributionsQuery}` with the parent and one filter per slot).
+ */
+export declare class SparkContributionAttributionComponent {
+  private readonly lang;
+  row: import("@angular/core").InputSignal<Record<string, any>>;
+  options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  ownerId: import("@angular/core").InputSignal<string | undefined>;
+  private readonly asked;
+  protected readonly historyLink: import("@angular/core").Signal<SparkContributionHistoryLink | null>;
+  protected readonly parts: import("@angular/core").Signal<{
+    kind: "by" | "at" | "history";
+    text: string;
+    iso?: string;
+    title?: string;
+  }[]>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkContributionAttributionComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkContributionAttributionComponent, "spark-contribution-attribution", never, {
+    "row": {
+      "alias": "row";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+    "ownerId": {
+      "alias": "ownerId";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** The source of every generated `{Target}{Property}Contributions` query (`ContributionDescriptor.ContributionsQueryMethod`). */
+export declare const SPARK_CONTRIBUTIONS_QUERY_SOURCE = "Custom.SparkContributionsOfTarget";
+/** `POST /spark/po/revert-contribution` (the Contributions server package). */
+export declare const SPARK_REVERT_CONTRIBUTION_PATH = "/po/revert-contribution";
+/** Whether `query` is a generated contributions query (its rows are contributions). */
+export declare function isContributionsQuery(query: Pick<SparkQuery, 'source'> | null | undefined): boolean;
+/**
+ * Makes a contribution current again: every newer visible version of its slot is hidden (reason
+ * `reverted`), atomically, by the server. The response's notice ("…newer version(s) were hidden") is
+ * dispatched like every operation. Rejects with the server's error (400 "restore it first" for a
+ * hidden one, 404 without the right).
+ */
+export declare function revertContribution(spark: SparkService, objectTypeId: string, id: string): Promise<void>;
+/**
+ * "Revert to this version" in the row menu of a contributions query — for holders of
+ * `RevertContribution/{type}`, outside the recycle bin. Asks first; refreshes the list afterwards.
+ */
+export declare const sparkRevertContributionRowAction: SparkQueryRowAction;
+/**
+ * "Revert to this version" on a contribution's detail page (a `SPARK_DETAIL_ACTIONS` entry): shown for
+ * `RevertContribution/{type}` holders on a generated contribution type (one that has the generated
+ * contributions query), outside the recycle bin. Reloads the page afterwards.
+ */
+export declare class SparkRevertContributionComponent {
+  private readonly spark;
+  private readonly lang;
+  context: import("@angular/core").InputSignal<SparkDetailContext>;
+  /** Whether the type is a generated contribution type: it has the generated contributions query. */
+  private readonly isContributionType;
+  protected readonly offered: import("@angular/core").Signal<boolean>;
+  protected readonly busy: import("@angular/core").WritableSignal<boolean>;
+  protected readonly error: import("@angular/core").WritableSignal<string | null>;
+  constructor();
+  revert(): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkRevertContributionComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkRevertContributionComponent, "spark-revert-contribution", never, {
+    "context": {
+      "alias": "context";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Adds the Contributions UI to the pages `sparkRoutes()` routes to — no routes of its own (PRD Q7):
+ * "Revert to this version" in the contributions query's row menu and on a contribution's detail page.
+ * Needs the server package `MintPlayer.Spark.Contributions`.
+ *
+ * ```ts
+ * providers: [
+ *   provideSpark(...),
+ *   provideSparkContributions(),
+ *   provideSparkAttributeRenderers([...sparkContributionRenderers, ...yourRenderers]),
+ * ]
+ * ```
+ *
+ * The renderers are registered with the app's own, because `provideSparkAttributeRenderers` takes one
+ * list: see {@link sparkContributionRenderers}.
+ */
+export declare function provideSparkContributions(options?: {
+  detailActionPriority?: number;
+}): Provider[];
+/**
+ * The two renderers the Contributions model names:
+ *
+ * - `contributionAttribution` — an AsDetail **row** renderer: "by Alice · 3 days ago · History (4)"
+ *   once per row, in place of the `ContributorName`/`UpdatedAt`/`ContributionCount` columns;
+ * - `lineDiff` — a detail renderer, generic: a text diffed line by line against a text of another
+ *   object (Contributions seeds it on a contribution's text values, against the current version).
+ */
+export declare const sparkContributionRenderers: SparkAttributeRendererRegistration[];