@mintplayer/ng-spark 22.31.0 → 22.33.0

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

@@ -0,0 +1,340 @@
+import { Color } from "@mintplayer/ng-bootstrap";
+import { SparkAttributeColumnRenderer, SparkAttributeDetailRenderer, SparkAttributeRendererRegistration } from "@mintplayer/ng-spark/renderers";
+import * as i0 from "@angular/core";
+import { Provider } from "@angular/core";
+import { TrendPoint, TrendSeries } from "@mintplayer/ng-bootstrap/charts/trend";
+/** A Bootstrap theme colour a band paints with: `bg-*` on a bar, `--bs-*` on a gauge, `text-bg-*` on a grade. */
+export type SparkScoreColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark';
+/**
+ * One band of a score scale: it applies to a value `>= min`. The band without a `min` is the floor,
+ * applying to everything below the lowest `min`. Bands may be listed in any order; the highest `min`
+ * the value reaches wins.
+ */
+export interface SparkScoreBand {
+  /** Inclusive lower bound. Omit for the floor band. */
+  min?: number;
+  color: SparkScoreColor;
+  /** A grade shown next to a gauge ("A"). Ignored by the threshold bar. */
+  label?: string;
+}
+/**
+ * The bands a `bands` / `grades` option accepts: a list, or the name of a preset (so a model's
+ * `rendererOptions` JSON, which cannot reference a TypeScript constant, can still pick one).
+ */
+export type SparkScoreBandsOption = readonly SparkScoreBand[] | 'traffic-light' | 'letter-grades';
+/**
+ * Green from 80, amber from 60, red below: the coverage thresholds the CodeCoverage badge and bar
+ * have always used. The default of every score renderer.
+ */
+export declare const sparkTrafficLightBands: readonly SparkScoreBand[];
+/** A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 50, else F: the grade scale of a 0–100 score (SeoTester). */
+export declare const sparkLetterGrades: readonly SparkScoreBand[];
+/** The bands an option names, or `fallback` for an absent or unrecognised one. */
+export declare function resolveSparkScoreBands(option: unknown, fallback?: readonly SparkScoreBand[]): readonly SparkScoreBand[];
+/** The band `value` falls in: the one with the highest `min` it reaches, else the floor, else none. */
+export declare function sparkScoreBand(value: number | null | undefined, bands: readonly SparkScoreBand[]): SparkScoreBand | null;
+/** The ng-bootstrap {@link Color} of `value`'s band; `secondary` when there is no value or no band. */
+export declare function sparkScoreColor(value: number | null | undefined, bands?: readonly SparkScoreBand[]): Color;
+/**
+ * A cell value as a number, or null for "no value". Numbers pass through, numeric strings parse,
+ * and null, undefined, the empty string and anything unparseable are no value. Never 0: an absent
+ * measurement must not draw as a real zero.
+ */
+export declare function toSparkScoreNumber(raw: unknown): number | null;
+/** `rendererOptions` of the `spark-threshold-bar` renderer. Every member is optional. */
+export interface SparkThresholdBarOptions {
+  /** Scale minimum. Default 0. */
+  min?: number;
+  /** Scale maximum. Default 100. */
+  max?: number;
+  /** Colour bands. Default `'traffic-light'` (green ≥ 80, amber ≥ 60, red below). */
+  bands?: SparkScoreBandsOption;
+  /** Decimals of the shown value. Default 1. */
+  decimals?: number;
+  /** Text after the shown value. Default `'%'`. */
+  suffix?: string;
+  /** The bar's accessible name. Default `'Value'`. */
+  label?: string;
+  /** CSS width of the bar. Default `'80px'`. */
+  width?: string;
+  /** CSS height of the bar. Default `'8px'`. */
+  height?: string;
+  /** Show the value as text next to the bar. Default true. */
+  showValue?: boolean;
+}
+interface ThresholdBarView {
+  value: number;
+  text: string;
+  color: Color;
+}
+/**
+ * The `spark-threshold-bar` renderer: a compact progress bar coloured by the band the value falls
+ * in, with the value next to it. No value (null, undefined, empty, unparseable) draws a muted dash
+ * rather than an empty bar, which would read as a real 0. The colour comes from the unrounded value,
+ * so 59.95 shows "60.0%" yet stays below a 60 threshold.
+ *
+ * Generalised from CodeCoverage's coverage bar, which is this renderer with `label: 'Coverage'`.
+ */
+export declare class SparkThresholdBarComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly settings: import("@angular/core").Signal<{
+    min: number;
+    max: number;
+    bands: readonly import("@mintplayer/ng-spark/score-renderers").SparkScoreBand[];
+    decimals: number;
+    suffix: string;
+    label: string;
+    width: string;
+    height: string;
+    showValue: boolean;
+  }>;
+  protected readonly view: import("@angular/core").Signal<ThresholdBarView | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkThresholdBarComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkThresholdBarComponent, "spark-threshold-bar", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** `rendererOptions` of the `spark-delta` renderer. Every member is optional. */
+export interface SparkDeltaOptions {
+  /** Decimals of the shown change. Default 1. */
+  decimals?: number;
+  /** A rise is good (green) and a drop bad (red). Set false for a cost, an error count, a load time. Default true. */
+  higherIsBetter?: boolean;
+  /** Text after the number, e.g. `' pt'` or `'%'`. Default none. */
+  suffix?: string;
+  /** Text for "no comparison". Default `'—'`. */
+  empty?: string;
+}
+/** How a delta reads: the text and its tone. */
+export interface SparkDeltaView {
+  /** The raw change is positive. Rounding does not change it: +0.04 at one decimal is `+0.0`, still up. */
+  up: boolean;
+  /** The raw change is negative. */
+  down: boolean;
+  /** `+1.3`, `-0.3`, `0.0`, or the empty text when there is nothing to compare. */
+  text: string;
+  /** `text-success`, `text-danger` or `text-muted`, honouring `higherIsBetter`. */
+  tone: 'text-success' | 'text-danger' | 'text-muted';
+}
+/**
+ * Formats a signed change. No value (null, undefined, empty, unparseable) is the empty text and
+ * never `0.0`, which would claim a comparison that did not happen; an exact zero is a real, neutral
+ * comparison.
+ */
+export declare function formatSparkDelta(raw: unknown, options?: SparkDeltaOptions | Record<string, any> | null): SparkDeltaView;
+/**
+ * The `spark-delta` renderer: a signed change, green when it improves and red when it worsens
+ * (`higherIsBetter`), muted for no change, and a muted dash when there is nothing to compare.
+ *
+ * Generalised from CodeCoverage's coverage delta, which is this renderer with its defaults.
+ */
+export declare class SparkDeltaComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly view: import("@angular/core").Signal<SparkDeltaView>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkDeltaComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkDeltaComponent, "spark-delta", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** `rendererOptions` of the `spark-trend` renderer. Every member is optional. */
+export interface SparkTrendOptions {
+  /** `'sparkline'` (default): a compact inline line for a cell. `'chart'`: an interactive chart with axes. */
+  display?: 'sparkline' | 'chart';
+  /** Fixed scale minimum, e.g. 0 for a percentage. Default: fitted to the data. */
+  yMin?: number;
+  /** Fixed scale maximum, e.g. 100 for a percentage. Default: fitted to the data. */
+  yMax?: number;
+  /** Accessible name of the line or chart. */
+  label?: string;
+  /** Fewer points than this draw the dash: one point is not a trend. Default 2. */
+  minPoints?: number;
+  /** Sparkline CSS width. Default `'90px'`. */
+  width?: string;
+  /** Sparkline CSS height. Default `'24px'`. */
+  height?: string;
+  /** Chart only: a goal line at this value. */
+  goal?: number;
+  /** Chart only: the goal line's label. */
+  goalLabel?: string;
+  /** Chart only: the series id. Default `'value'`. */
+  seriesId?: string;
+  /** Chart only: the series label (legend, tooltip). Default `label`. */
+  seriesLabel?: string;
+}
+/** One point of a trend value: a plain number (x = its index), null for a gap, or an explicit `{ x, y }`. */
+export type SparkTrendValuePoint = number | null | {
+  x: number | Date;
+  y: number | null;
+};
+/**
+ * The value as `{ x, y }` points, or null when it is not a series or has fewer than `minPoints`.
+ * A number is a point at its index; an array holding anything else is not a series.
+ */
+export declare function toSparkTrendPoints(value: unknown, minPoints?: number): TrendPoint[] | null;
+/** What the three trend components share: the inputs, the options read once, and the points. */
+declare abstract class SparkTrendBase implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly settings: import("@angular/core").Signal<{
+    display: "sparkline" | "chart";
+    yMin: number | undefined;
+    yMax: number | undefined;
+    label: string | undefined;
+    minPoints: number;
+    width: string;
+    height: string;
+    goal: number | undefined;
+    goalLabel: string | undefined;
+    seriesId: string;
+    seriesLabel: string;
+  }>;
+  protected readonly points: import("@angular/core").Signal<import("@mintplayer/web-components/charts/core").TrendPoint[] | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkTrendBase, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<SparkTrendBase, never, never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The sparkline half of `spark-trend`, usable on its own: a compact line for a cell, or a muted dash.
+ * Imports only the sparkline, so an app drawing sparklines does not load the trend chart with them.
+ */
+export declare class SparkTrendSparklineComponent extends SparkTrendBase {
+  protected ys(points: TrendPoint[]): (number | null)[];
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkTrendSparklineComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkTrendSparklineComponent, "spark-trend-sparkline", never, {}, {}, never, never, true, never>;
+}
+/**
+ * The chart half of `spark-trend`, usable on its own: an interactive trend chart of one series with
+ * an optional goal line, or a muted dash. Imports only the trend chart.
+ */
+export declare class SparkTrendChartComponent extends SparkTrendBase {
+  protected readonly series: import("@angular/core").Signal<TrendSeries[]>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkTrendChartComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkTrendChartComponent, "spark-trend-chart", never, {}, {}, never, never, true, never>;
+}
+/**
+ * The `spark-trend` renderer: a series as a sparkline in a cell, or with `display: 'chart'` as an
+ * interactive trend chart. The value is an array of numbers (null for a gap) or of `{ x, y }` points
+ * (x a number or a Date); anything else, or fewer than `minPoints` points, draws a muted dash.
+ *
+ * Generalised from CodeCoverage's repository sparkline (90×24 on a fixed 0–100 scale) and its
+ * "coverage over time" chart (an 80% goal line). Registering this renderer loads both charts; a
+ * template that needs only one uses `<spark-trend-sparkline>` or `<spark-trend-chart>`.
+ */
+export declare class SparkTrendComponent extends SparkTrendBase {
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkTrendComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkTrendComponent, "spark-trend", never, {}, {}, never, never, true, never>;
+}
+/** `rendererOptions` of the `spark-gauge` renderer. Every member is optional. */
+export interface SparkGaugeOptions {
+  /** Scale minimum. Default 0. */
+  min?: number;
+  /** Scale maximum. Default 100. */
+  max?: number;
+  /**
+   * The bands that colour the ring and, when they carry a `label`, name the grade drawn next to it.
+   * `'letter-grades'` is A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 50, else F. Default `'traffic-light'` (no grade).
+   */
+  bands?: SparkScoreBandsOption;
+  /** Decimals of the score in the ring. Default 0. */
+  decimals?: number;
+  /** Text after the score, e.g. `'%'`. Default none. */
+  suffix?: string;
+  /** The gauge's accessible name. Default `'Score'`. */
+  label?: string;
+  /** Diameter in CSS pixels. Default 48. */
+  size?: number;
+}
+interface GaugeView {
+  value: number;
+  text: string;
+  color: SparkScoreColor;
+  grade: string | null;
+  /** The grade badge's colour (the band's). */
+  badge: Color;
+  /** Arc length on a ring of circumference 100: the share of the scale reached, clamped to 0–100. */
+  arc: number;
+}
+/**
+ * The `spark-gauge` renderer: a score as a ring filled to its share of the scale, coloured by its
+ * band, with the score inside and the band's grade (when the bands carry labels) beside it. No value
+ * draws a muted dash rather than an empty ring, which would read as a real 0.
+ *
+ * Exposed as an ARIA `meter` whose value text includes the grade ("72 (C)").
+ */
+export declare class SparkGaugeComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly settings: import("@angular/core").Signal<{
+    min: number;
+    max: number;
+    bands: readonly import("@mintplayer/ng-spark/score-renderers").SparkScoreBand[];
+    decimals: number;
+    suffix: string;
+    label: string;
+    size: number;
+  }>;
+  protected readonly view: import("@angular/core").Signal<GaugeView | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkGaugeComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkGaugeComponent, "spark-gauge", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The score renderers under their generic names, each drawing both a grid cell and a detail value.
+ * Configured per attribute through the model's `rendererOptions`.
+ */
+export declare const sparkScoreRenderers: readonly SparkAttributeRendererRegistration[];
+/**
+ * Registers the score renderers (`spark-gauge`, `spark-threshold-bar`, `spark-trend`, `spark-delta`)
+ * together with the app's own. Use it **instead of** `provideSparkAttributeRenderers`, not next to
+ * it: both provide the one renderer list, and the last provider would win.
+ *
+ * The app's registrations come first, so an app renderer of the same name replaces a score renderer.
+ *
+ * @example
+ * provideSparkScoreRenderers([
+ *   { name: 'coverage-delta', columnComponent: SparkDeltaComponent, detailComponent: SparkDeltaComponent },
+ * ])
+ */
+export declare function provideSparkScoreRenderers(renderers?: SparkAttributeRendererRegistration[]): Provider;

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

@@ -1,5 +1,6 @@
-import { CustomActionDefinition, DistinctValuesResult, EntityPermissions, EntityType, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, ProgramUnitsConfiguration, QueryColumnFilter, QueryResult, RetryActionPayload, RetryActionResult, SparkDeletedFilter, SparkQuery, StreamingMessage, TranslatedString } from "@mintplayer/ng-spark/models";
+import { CustomActionDefinition, DistinctValuesResult, EntityPermissions, EntityType, LivePoEvent, LiveQueryEvent, LiveQueryRequest, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, ProgramUnitsConfiguration, QueryColumnFilter, QueryResult, RetryActionPayload, RetryActionResult, SparkDeletedFilter, SparkQuery, TranslatedString } from "@mintplayer/ng-spark/models";
 import * as i0 from "@angular/core";
+import { Injector, Signal } from "@angular/core";
 import { Observable } from "rxjs";
 import { SortColumn } from "@mintplayer/pagination";
 import { SafeHtml } from "@angular/platform-browser";
@@ -35,19 +36,105 @@ export declare class SparkLanguageService {
   private loadTranslations;
   setLanguage(lang: string): void;
   resolve(ts: TranslatedString | undefined): string;
-  t(key: string): string;
+  /**
+   * The text of `key` in the current language. When there is none (unknown key, empty text, or the
+   * translations have not arrived yet) it is `fallback` when given, else the key itself, so
+   * `t('spark.query.unavailable', 'This list is not available.')` never shows a raw key to a user.
+   */
+  t(key: string, fallback?: string): string;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkLanguageService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-export declare class SparkStreamingService {
+/** Options of {@link SparkLiveService.watchPersistentObject}. */
+export interface LivePoWatchOptions {
+  /** The soft-deletion mode the object is loaded with, as `/spark/po/load` takes it. */
+  deleted?: SparkDeletedFilter | null;
+}
+/** Options of the signal helpers: an injector when called outside an injection context. */
+export interface LiveSignalOptions {
+  injector?: Injector;
+}
+/**
+ * Live updates over ONE lazy WebSocket to `/spark/live` (X4; `docs/guide-live-updates.md`).
+ *
+ * - Subscriptions are ref-counted by a canonical JSON of their request, so two components watching the
+ *   same object or the same query page share one server subscription; the last one to leave unsubscribes,
+ *   and the socket closes when nothing is watched.
+ * - `po`/`result` replace the held state and `poPatch`/`patch` are applied to it, so a watcher always
+ *   receives the whole object or page.
+ * - A subscription's `error` or `gone` ends that subscription only: it is never a reason to reconnect.
+ *   (The streaming service it replaces retried ten times on "access denied".)
+ * - The socket reconnects with exponential backoff and jitter after a network loss or a server restart,
+ *   then resubscribes everything, which yields fresh snapshots. `4401` reconnects at once (the cookie is
+ *   validated afresh) unless it repeats within seconds; `4429` and `1009` are surfaced, not retried.
+ * - The socket and its timers run outside the Angular zone; only emissions re-enter it.
+ */
+export declare class SparkLiveService {
   private readonly config;
   private readonly baseUrl;
   private readonly ngZone;
-  connectToStreamingQuery(queryId: string): Observable<StreamingMessage>;
+  private readonly entries;
+  private readonly bySub;
+  private nextSub;
+  private socket;
+  private reconnectTimer;
+  private attempt;
+  private lastReauthAt;
+  /**
+   * Follows one persistent object: `po` with the object as `/spark/po/load` returns it (patches applied),
+   * then `gone` or `error`, after either of which the stream completes.
+   */
+  watchPersistentObject(objectTypeId: string, id: string, options?: LivePoWatchOptions): Observable<LivePoEvent>;
+  /**
+   * Follows one query page: `result` with the page as `/spark/queries/execute` returns it (patches applied),
+   * or `error`, after which the stream completes.
+   *
+   * Given an observable, the page follows it: a new request is sent as an `update` of the same server
+   * subscription when this watcher has it to itself, and joins (or opens) the subscription of the new request
+   * otherwise. `null` leaves the current subscription without completing.
+   */
+  watchQuery(request: LiveQueryRequest | Observable<LiveQueryRequest | null>): Observable<LiveQueryEvent>;
+  /**
+   * A signal of one live object for a custom page: `null` until the first state (and after an `error`),
+   * the object afterwards, `'gone'` once it is deleted or no longer readable. Follows `type` and `id`;
+   * a null or empty id watches nothing. Call it in an injection context or pass an injector.
+   */
+  livePersistentObject(type: Signal<string>, id: Signal<string | null | undefined>, options?: LiveSignalOptions): Signal<PersistentObject | null | 'gone'>;
+  /**
+   * A signal of one live query page for a custom page: `null` until the first page (and after an `error`).
+   * A changed request (page, sort, search) is sent as an `update`; `null` watches nothing. Call it in an
+   * injection context or pass an injector.
+   */
+  liveQuery(request: Signal<LiveQueryRequest | null>, options?: LiveSignalOptions): Signal<QueryResult | null>;
+  private attach;
+  private update;
+  private detach;
+  private forget;
+  /** Ends one subscription for all its watchers: the event, then completion. */
+  private end;
+  /** Ends every subscription with a socket-level failure and drops the socket without reconnecting. */
+  private failAll;
+  private isOpen;
+  private ensureSocket;
+  private open;
+  private onClose;
+  /**
+   * Closes the socket once nothing is watched — after a microtask, so a watcher that switches objects
+   * (leave one, watch the next in the same turn) keeps the socket instead of reconnecting.
+   */
+  private closeIfIdle;
+  private closeSocket;
+  private sendSubscribe;
+  private send;
+  private onFrame;
+  private broadcast;
+  private emit;
   private buildWebSocketUrl;
-  static ɵfac: i0.ɵɵFactoryDeclaration<SparkStreamingService, never>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkLiveService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
+/** JSON with object keys sorted and `null`/`undefined` fields dropped, so equal requests key equal. */
+export declare function canonicalJson(value: unknown): string;
 /**
  * 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` —
@@ -528,4 +615,57 @@ export interface SparkDatatableLabels {
  * 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;
+export declare function sparkDatatableLabels(lang: SparkLanguageService): SparkDatatableLabels;
+/** What {@link describeSparkError} needs of the language service (`SparkLanguageService` fits). */
+export interface SparkErrorLanguage {
+  t(key: string, fallback?: string): string;
+  resolve(ts: TranslatedString | undefined): string;
+}
+/**
+ * The seconds a refused call (429) was told to wait: the envelope's `result.retryAfterSeconds` (core's
+ * `ClientResult.Throttled`), a bare body's `retryAfterSeconds`, else the `Retry-After` header in seconds. `null` when
+ * the refusal named no wait, or the error is not a 429.
+ */
+export declare function sparkRetryAfterSeconds(e: unknown): number | null;
+/**
+ * A wait in words, rounded the way a person says it: "a few seconds", "1 minute", "12 minutes", "3 hours", "2 days"
+ * (keys `spark.wait.*`, `{0}` is the number).
+ */
+export declare function formatSparkWait(seconds: number, lang: Pick<SparkErrorLanguage, 't'>): string;
+/**
+ * The readable reason a Spark call failed, for an error banner: the first validation message (a `400`'s
+ * `result.errors`), else the server's `result.error` (the envelope every action and write answers with), else a bare
+ * body's `error`, else `fallback`. A refusal with a wait (429 + `retryAfterSeconds`/`Retry-After`) gets "Try again in
+ * 3 hours." appended, so a quota or cool-down says when, not just no.
+ */
+export declare function describeSparkError(e: unknown, lang: SparkErrorLanguage, fallback: string): string;
+/**
+ * Sends the language the user picked to the server, as `Accept-Language`.
+ *
+ * `SparkLanguageService` keeps the choice in `localStorage` and never puts it on the wire: it is a
+ * client-side concern, because almost everything translated reaches the client as a whole
+ * `TranslatedString` and is resolved by the `resolveTranslation` pipe. Server-*resolved* strings
+ * are the exception (CodeCoverage's Home page title, SeoTester's refusals and its dashboard title) because a `PersistentObject`'s breadcrumb and an
+ * attribute's value are plain strings with nowhere to carry three languages.
+ *
+ * Spark resolves those through `IRequestCultureResolver`, which reads `Accept-Language`. Without
+ * this the browser's header wins, so a visitor whose browser prefers Dutch sees a Dutch title
+ * above an otherwise English page, and switching the language selector never changes it.
+ *
+ * ⚠️ Reads the module-level `currentLanguage` signal, and **must not** `inject(SparkLanguageService)`.
+ * That service fetches `/culture` and `/translations` from its own constructor, so an interceptor
+ * that injects it is re-entered while it is still being constructed: Angular throws NG0200 for
+ * every request, the culture and translation payloads never arrive, and the whole UI renders raw
+ * keys ("app.title") with the language selector missing. `currentLanguage` is the same value
+ * without the cycle — the service writes it on load and on every change.
+ *
+ * Empty until `/culture` resolves, which is exactly the window where there is no user choice to
+ * honour yet; those first requests fall through to the browser's own header.
+ */
+export declare const sparkLanguageInterceptor: HttpInterceptorFn;
+/**
+ * `provideHttpClient(...withSparkLanguage())`: registers {@link sparkLanguageInterceptor}, so server-resolved texts
+ * (breadcrumbs, action messages, refusals) follow the language selector instead of the browser's preference.
+ * Moved from CodeCoverage (M11), where it was the app's own; SeoTester needed the same.
+ */
+export declare function withSparkLanguage(): HttpFeature<HttpFeatureKind>[];

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

@@ -0,0 +1,67 @@
+import { Color } from "@mintplayer/ng-bootstrap";
+import { PersistentObject, PersistentObjectAttribute, QueryColumn, QueryResult, QueryResultItem, TranslatedString } from "@mintplayer/ng-spark/models";
+import * as i0 from "@angular/core";
+/** What `POST /spark/share/load` answers: the declared attributes and the first page of each declared child query. */
+export interface SparkSharedObject {
+  id: string;
+  type: string;
+  /** The type's label (the model's, translated); the page's heading. */
+  label?: TranslatedString | null;
+  attributes: PersistentObjectAttribute[];
+  /** By query name. */
+  queries: Record<string, QueryResult>;
+  /** Each shown query's label, by query name; the tables' headings. */
+  queryLabels?: Record<string, TranslatedString | null>;
+}
+type State = 'loading' | 'ready' | 'notFound' | 'failed';
+/**
+ * The read-only page of a share link (`docs/seo_analyzer_PRD.md` X6, D31), routed by `withShareRoutes()`:
+ * exactly what `POST /spark/share/load` returned, the object's attributes through the same cells (and
+ * custom renderers, such as the score renderers) as the rest of Spark, and one read-only table per
+ * child query, paged through `POST /spark/share/query`. Every refusal reads as the one "this link does
+ * not work" (`share.notFound`), since the server answers every refusal with the same 404. No signed-in
+ * user, no links into the app, no assumptions about the surrounding chrome.
+ */
+export declare class SparkSharedObjectComponent {
+  private readonly http;
+  private readonly route;
+  private readonly language;
+  private readonly baseUrl;
+  private readonly cellPipe;
+  protected readonly colors: typeof Color;
+  private readonly type;
+  private readonly token;
+  private readonly id;
+  readonly state: import("@angular/core").WritableSignal<State>;
+  readonly shared: import("@angular/core").WritableSignal<SparkSharedObject | null>;
+  /** The page shown of each child query, by name: the first from the load, then whatever was paged to. */
+  readonly pages: import("@angular/core").WritableSignal<Record<string, QueryResult>>;
+  readonly busy: import("@angular/core").WritableSignal<boolean>;
+  /** A passing problem (rate limit, network) shown above the content, which stays. */
+  readonly notice: import("@angular/core").WritableSignal<string | null>;
+  /** The object in the shape renderers receive as `item`. */
+  protected readonly object: import("@angular/core").Signal<PersistentObject | null>;
+  protected readonly attributeCells: import("@angular/core").Signal<{
+    attribute: PersistentObjectAttribute;
+    display: any;
+    value: any;
+  }[]>;
+  protected readonly queryTables: import("@angular/core").Signal<{
+    name: string;
+    label: TranslatedString | undefined;
+    result: QueryResult;
+    columns: QueryColumn[];
+    last: number;
+  }[]>;
+  constructor();
+  protected t(key: string): string;
+  protected display(column: QueryColumn, item: QueryResultItem): unknown;
+  protected raw(item: QueryResultItem, column: QueryColumn): unknown;
+  load(): Promise<void>;
+  /** Shows the page of `query` that starts at `skip`, the same size as the one shown. */
+  page(query: string, skip: number): Promise<void>;
+  private post;
+  private fail;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkSharedObjectComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkSharedObjectComponent, "spark-shared-object", never, {}, {}, never, never, true, never>;
+}

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

@@ -0,0 +1,26 @@
+import { Type } from "@angular/core";
+import { Routes } from "@angular/router";
+import { SparkSharedObject } from "@mintplayer/ng-spark/share/page";
+/** Options of {@link withShareRoutes}. */
+export interface SparkShareRoutesOptions {
+  /** The route path; it must hold `:type` and `:token`. Default `shared/:type/:token`, matching the server's `Spark:Share:LinkPath` (`/shared`). */
+  path?: string;
+  /** A page to use instead of `SparkSharedObjectComponent`. */
+  component?: Type<unknown>;
+}
+/**
+ * The page a share link opens (`docs/seo_analyzer_PRD.md` X6, D31): `{origin}/shared/{type}/{token}?id={id}`.
+ * Anonymous by design (the token is the credential), so it carries no guard; put it where no app chrome
+ * assumes a signed-in user:
+ *
+ * ```ts
+ * export const routes: Routes = [
+ *   ...withShareRoutes(),
+ *   { path: '', component: ShellComponent, children: [...sparkRoutes()] },
+ * ];
+ * ```
+ *
+ * Moving the page means setting `Spark:Share:LinkPath` to match, so the links the server makes follow.
+ */
+export declare function withShareRoutes(options?: SparkShareRoutesOptions): Routes;
+export type { SparkSharedObject };