@mintplayer/ng-spark 22.31.0 → 22.33.0

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

@@ -0,0 +1,72 @@
+import { CanActivateFn } from "@angular/router";
+import { SparkAuthRouteEntry } from "@mintplayer/ng-spark/auth/models";
+import { SparkAuthRoutesFeature } from "@mintplayer/ng-spark/auth/routes";
+import * as i0 from "@angular/core";
+import { OnInit } from "@angular/core";
+/**
+ * The organizations package's one SPA page (`docs/seo_analyzer_PRD.md` X11): the target of a mailed
+ * invitation or join request, `organizations/accept/:token?id=<invitationId>`, as a `sparkAuthRoutes()`
+ * feature:
+ *
+ * ```ts
+ * sparkAuthRoutes(withExternalLogin(), withAccount(), withOrganizationRoutes())
+ * ```
+ *
+ * The page needs a signed-in user: the guard (default `[sparkAuthGuard]`) sends everyone else to the
+ * sign-in page and back. Organizations, members and invitations themselves are the generic `po/:type`
+ * and `query/:id` screens. Moving the page means setting `Spark:Organizations:AcceptPath` to match, so
+ * the mailed links follow.
+ */
+export declare function withOrganizationRoutes(options?: {
+  canActivate?: CanActivateFn[];
+  accept?: SparkAuthRouteEntry;
+}): SparkAuthRoutesFeature;
+/** One organization the switcher offers (`GET /spark/organizations/current`). */
+export interface SparkOrganizationChoice {
+  id: string;
+  name: string;
+  isPersonal: boolean;
+}
+/** What `/spark/organizations/current` answers: the chosen organization (`null`: all of them) and the caller's organizations. */
+export interface SparkCurrentOrganization {
+  current: string | null;
+  organizations: SparkOrganizationChoice[];
+}
+/** English fallbacks of the switcher's texts (`organizations.spa.*` in the organizations package's translations). */
+export declare const SPARK_ORGANIZATION_SWITCHER_TEXTS: Record<string, string>;
+/**
+ * The organization switcher for an app's top bar (`docs/seo_analyzer_PRD.md` Q-M11a): "All organizations" or one
+ * of the caller's organizations. The server keeps the choice (a cookie it checks against the caller's memberships
+ * on every request), lists of organization-owned rows show only the chosen organization's, and a new row whose
+ * form names no organization lands in it. A detail page, a sub-query and the organization list are not narrowed.
+ *
+ * ```html
+ * @if (auth.isAuthenticated()) { <spark-organization-switcher /> }
+ * ```
+ *
+ * Renders nothing for a user in one organization (or none), so it can sit in the top bar unconditionally. A
+ * choice reloads the page (`reloadOnChange`), so every grid, live list and cached page reads the new scope.
+ */
+export declare class SparkOrganizationSwitcherComponent implements OnInit {
+  private readonly http;
+  private readonly language;
+  private readonly document;
+  /** Reload the page after a choice, so every list reads the new scope. Default true. */
+  readonly reloadOnChange: import("@angular/core").InputSignal<boolean>;
+  readonly state: import("@angular/core").WritableSignal<SparkCurrentOrganization | null>;
+  readonly busy: import("@angular/core").WritableSignal<boolean>;
+  ngOnInit(): Promise<void>;
+  protected t(key: string): string;
+  protected label(organization: SparkOrganizationChoice): string;
+  /** Reloads the page; a seam for tests. */
+  protected reload(): void;
+  choose(organizationId: string | null): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkOrganizationSwitcherComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkOrganizationSwitcherComponent, "spark-organization-switcher", never, {
+    "reloadOnChange": {
+      "alias": "reloadOnChange";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}

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

@@ -46,6 +46,16 @@ export declare class AttributeValuePipe implements PipeTransform {
   static ɵfac: i0.ɵɵFactoryDeclaration<AttributeValuePipe, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<AttributeValuePipe, "attributeValue", true>;
 }
+/**
+ * A displayed value, or `-` when there is none: `null`, `undefined` or an empty (or blank) string. Unlike
+ * `value || '-'` it keeps the falsy values that are data: the number `0` (a page at depth 0, a count of 0) and `false`.
+ */
+export declare function sparkOrDash(value: unknown): unknown;
+export declare class OrDashPipe implements PipeTransform {
+  transform(value: unknown): unknown;
+  static ɵfac: i0.ɵɵFactoryDeclaration<OrDashPipe, never>;
+  static ɵpipe: i0.ɵɵPipeDeclaration<OrDashPipe, "orDash", true>;
+}
 export declare class RawAttributeValuePipe implements PipeTransform {
   transform(attrName: string, item: PersistentObject | null): any;
   static ɵfac: i0.ɵɵFactoryDeclaration<RawAttributeValuePipe, never>;

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

@@ -12,6 +12,7 @@ export declare class SparkPoDetailComponent {
   private readonly returnNavigation;
   private readonly queryRefresh;
   private readonly attributeRefresh;
+  private readonly live;
   protected readonly lang: SparkLanguageService;
   private readonly clientMethods;
   protected readonly rendererRegistry: import("@mintplayer/ng-spark/renderers").SparkAttributeRendererRegistration[];
@@ -45,12 +46,17 @@ export declare class SparkPoDetailComponent {
   queryActionsTemplate: import("@angular/core").InputSignal<TemplateRef<any> | null>;
   edited: import("@angular/core").OutputEmitterRef<void>;
   deleted: import("@angular/core").OutputEmitterRef<void>;
+  /** After an action succeeded; `result` is what it handed to `CustomActionArgs.SetResult` (a download url, a new id). */
   customActionExecuted: import("@angular/core").OutputEmitterRef<{
     action: CustomActionDefinition;
     item: PersistentObject;
+    result?: unknown;
   }>;
   colors: typeof Color;
+  /** The page could not be loaded: shown instead of the page. */
   errorMessage: import("@angular/core").WritableSignal<string | null>;
+  /** A custom action failed or was refused: shown above the page, which stays (it used to replace the page). */
+  actionError: import("@angular/core").WritableSignal<string | null>;
   entityType: import("@angular/core").WritableSignal<EntityType | null>;
   /** The sub-queries rendered as cards below the form, in object form (#460, D17). */
   protected readonly subQueries: import("@angular/core").Signal<import("@mintplayer/ng-spark/models").SparkSubQuery[]>;
@@ -96,6 +102,21 @@ export declare class SparkPoDetailComponent {
    */
   visibleCustomActions: import("@angular/core").Signal<CustomActionDefinition[]>;
   constructor();
+  /** The live subscription of the object on screen, while its type is live; keyed so a reload keeps it. */
+  private liveSubscription;
+  private liveKey;
+  /** The catalogue and rights of the last load, so a pushed object re-derives its Edit/Delete/actions. */
+  private loadedActions;
+  /**
+   * Follows the object when its type is live: every push replaces the shown object and re-derives Edit,
+   * Delete and the custom actions from its own `can`/`disabledActions`, as a load does. `gone` (deleted, or
+   * no longer readable — one answer) shows the unavailable state. A subscription `error` stops following
+   * and keeps the loaded object: the page still shows what the HTTP load returned.
+   */
+  private follow;
+  private stopFollowing;
+  /** The translation, or `fallback` while the key has none (`t` echoes a missing key). */
+  private translateOr;
   /**
    * Applies patched attribute values in place, without a re-fetch.
    *
@@ -109,6 +130,11 @@ export declare class SparkPoDetailComponent {
   private loadItem;
   /** (Re)loads the object, its type, rights and actions. Also what add-ons call via `context.reload()`. */
   load(): Promise<void>;
+  /**
+   * Edit, Delete and the custom actions for `item`, from the last load's catalogue and rights: on a load,
+   * and again on every live push, since `can` and `disabledActions` travel with the object.
+   */
+  private deriveActions;
   /**
    * Drawn from the loaded object's own `showedOn`, falling back to the model's (#264, G-Q3): an action sets
    * it per object in `OnLoadAsync` — a stolen car's police report number is shown, the model says `None`.

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

@@ -133,6 +133,7 @@ export declare class SparkPoEditComponent {
   private readonly route;
   private readonly router;
   private readonly sparkService;
+  private readonly live;
   private readonly language;
   /** `SparkConfig.conflictDialog.showChangedBy`: whether the conflict notice may name a user at all. */
   private readonly showChangedBy;
@@ -186,6 +187,36 @@ export declare class SparkPoEditComponent {
   private readonly form;
   private readonly locale;
   constructor();
+  private liveSubscription;
+  /** The newest version pushed while this form is open; considered whenever the form can take it. */
+  private latestPushed;
+  /**
+   * A newer version someone else saved while the user has unsaved edits: the form is left alone and a
+   * banner offers to review it. Null when there is none (or it has been adopted or reviewed).
+   */
+  readonly liveTheirs: import("@angular/core").WritableSignal<PersistentObject | null>;
+  protected readonly liveChangedText: import("@angular/core").Signal<string>;
+  protected readonly liveReviewText: import("@angular/core").Signal<string>;
+  /**
+   * Watches the object while the form is open, when its type is live. A newer version (another etag) is
+   * adopted silently while the form is untouched — base and form replaced, so the next save posts the new
+   * etag — and only offered (banner, then the three-way merge) once the user has edited. `gone` reads as a
+   * 409 `deleted`. The 409 on save stays the server-side guarantee; this only brings it forward.
+   */
+  private follow;
+  private stopFollowing;
+  /** Adopts the latest pushed version when the form is clean, or offers it when the form is dirty. */
+  private considerLivePush;
+  /** Whether the form holds edits: it differs from the object it was built from. */
+  isDirty(): boolean;
+  /**
+   * The banner's Review: the existing three-way merge of the loaded base, the user's edits and the pushed
+   * version. Nothing conflicts → applied, and their etag adopted; conflicts → the conflict dialog. Nothing
+   * is saved either way.
+   */
+  reviewLiveChange(): void;
+  /** The translation, or `fallback` while the key has none (`t` echoes a missing key). */
+  private translateOr;
   private onParamsChange;
   initFormData(): void;
   /**
@@ -239,6 +270,12 @@ export declare class SparkPoEditComponent {
    * reviews and saves, and the server's validation and business rules run again on the result.
    */
   private resolveConcurrencyConflict;
+  /**
+   * Merges this form onto `theirs`, three-way against the object as loaded: disjoint edits are applied
+   * and their etag adopted (with a notice); true conflicts open the dialog. Shared by the 409 path and
+   * the live banner's Review.
+   */
+  private mergeWith;
   /**
    * 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

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

@@ -1,6 +1,7 @@
 import * as i0 from "@angular/core";
 import { EnvironmentProviders, InjectionToken } from "@angular/core";
 import { SwRegistrationOptions } from "@angular/service-worker";
+import { Location } from "@angular/common";
 export interface SparkServiceWorkerOptions {
   /** Whether the worker registers. Default: `!isDevMode()`, so only production builds register it. */
   enabled?: boolean;
@@ -11,7 +12,8 @@ export interface SparkServiceWorkerOptions {
 }
 /**
  * Registers Angular's service worker with Spark's update policy (#464, Q1b); see
- * {@link SparkServiceWorkerUpdates} for what happens when a new version is deployed.
+ * {@link SparkServiceWorkerUpdates} for what happens when a new version is deployed, and
+ * {@link SparkNotificationClicks} for a push notification clicked while the application is open.
  *
  * The application also needs an `ngsw-config.json` with Spark's navigation exclusions and
  * `serviceWorker` in its production build configuration; see `docs/guide-pwa.md`.
@@ -86,4 +88,48 @@ export declare class SparkServiceWorkerUpdates {
   private writeReloadedFor;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkServiceWorkerUpdates, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
-}
+}
+/**
+ * Notification clicks while the application is open (`docs/seo_analyzer_PRD.md` X10, D30): a click on
+ * a push whose `notification.data.url` is on this origin becomes an in-app router navigation, so the
+ * page keeps its state instead of loading again.
+ *
+ * What it does NOT do, because Angular's service worker (ngsw) already does it: show the push, and
+ * open the page when the application is closed. The server sends Angular's payload,
+ * `{ notification: { title, body, tag, data: { url, notificationId, onActionClick: { default: {
+ * operation, url } } } } }`, and ngsw performs `onActionClick.default` itself on the click, then
+ * broadcasts the click to the open pages, which is what {@link SwPush.notificationClicks} reports here.
+ *
+ * ⚠️ The operation decides whether this handler matters. ngsw runs it BEFORE the broadcast:
+ * `navigateLastFocusedOrOpen` makes the focused page load the URL in full, so this handler then
+ * finds the router already there and does nothing; `focusLastFocusedOrOpen` focuses the open page
+ * without loading it (and opens the URL when no page is open), leaving the navigation to this handler.
+ *
+ * Active only in a browser with the service worker enabled; started by `provideSparkServiceWorker()`.
+ */
+export declare class SparkNotificationClicks {
+  private readonly swPush;
+  private readonly router;
+  private readonly location;
+  private readonly document;
+  private readonly platformId;
+  private readonly destroyRef;
+  private started;
+  /** Starts listening. Idempotent; called by the app initializer `provideSparkServiceWorker()` adds. */
+  start(): void;
+  private navigate;
+  /** A full page load (overridden in specs: jsdom cannot navigate). */
+  protected assign(href: string): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkNotificationClicks, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * The router URL for `url` when it points into this application, else `null`.
+ *
+ * `url` may be app-relative (`/runs/42`) or absolute. It is resolved against the document's base URI;
+ * only an `http(s)` URL on the page's own origin is in-app, and its path loses the `<base href>`
+ * (through `Location.normalize`) because the router works below it. Everything else (another origin,
+ * `javascript:`, `mailto:`, an unparseable value) is `null`, so a caller never hands data-borne URLs
+ * to the router or to `location.assign` unchecked.
+ */
+export declare function sparkInAppUrl(url: string | null | undefined, document: Document, location: Location | null): string | null;

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

@@ -3,7 +3,7 @@ import { TemplateRef } from "@angular/core";
 import { Color } from "@mintplayer/ng-bootstrap";
 import { SparkLanguageService } from "@mintplayer/ng-spark/services";
 import { SparkQueryToolbarAction } from "@mintplayer/ng-spark/grid";
-import { CustomActionDefinition, QueryColumn, QueryColumnFilter, QueryResultItem, SparkDeletedFilter, SparkSelectionModeSetting } from "@mintplayer/ng-spark/models";
+import { CustomActionDefinition, QueryColumnFilter, QueryResultItem, SparkDeletedFilter, SparkSelectionModeSetting } from "@mintplayer/ng-spark/models";
 import { SparkQueryListContext } from "@mintplayer/ng-spark/panels";
 /**
  * The routed query page: chrome around one {@link SparkQueryGridComponent}.
@@ -14,9 +14,11 @@ import { SparkQueryListContext } from "@mintplayer/ng-spark/panels";
  *    routes — `query/:queryId`, and `po/:type`, which resolves an entity type to a query. That
  *    second one is type-to-query resolution, not query rendering, and is why this component still
  *    exists rather than the router pointing at the grid.
- *  - **Streaming.** The websocket lives here so it stays out of every PO detail page's bundle;
- *    the snapshot is filtered and sorted client-side and handed to the grid as `[data]`.
- *  - The action bar, the caption, the LIVE badge, the search box and the New button.
+ *  - The action bar, the caption, the LIVE badge (the grid's `isLive()`), the search box and the
+ *    New button.
+ *
+ * Live updates are the grid's (X4): a live query is followed by `spark-query-grid` itself, with
+ * server-side paging, sort and search, so every embedded grid follows it too — not only this page.
  *
  * The grid itself — columns, cells, paging, the row link, selection, custom-action execution —
  * is the shared component. This page previously wrote out `<bs-datatable>` twice, once per
@@ -26,8 +28,6 @@ export declare class SparkQueryListComponent {
   private readonly route;
   private readonly router;
   private readonly sparkService;
-  private readonly streamingService;
-  private readonly destroyRef;
   protected readonly lang: SparkLanguageService;
   extraActionsTemplate: import("@angular/core").InputSignal<TemplateRef<void> | null>;
   showCustomActions: import("@angular/core").InputSignal<boolean>;
@@ -65,6 +65,8 @@ export declare class SparkQueryListComponent {
   protected readonly resultCount: import("@angular/core").Signal<number | null>;
   protected readonly isVirtualScrolling: import("@angular/core").Signal<boolean>;
   protected readonly gridError: import("@angular/core").Signal<string | null>;
+  /** Whether the grid follows the query over `/spark/live` right now: the LIVE badge. */
+  protected readonly isLive: import("@angular/core").Signal<boolean>;
   protected readonly permissions: import("@angular/core").Signal<import("@mintplayer/ng-spark/models").EntityPermissions | null>;
   /** Add-on buttons for the action bar (#460, `SPARK_QUERY_LIST_ACTIONS`), e.g. the Deleted toggle. */
   protected readonly listActions: import("@mintplayer/ng-spark/panels").SparkQueryListAction[];
@@ -89,19 +91,6 @@ export declare class SparkQueryListComponent {
   protected toolbarActionUnavailableReason(action: SparkQueryToolbarAction): string | null;
   protected runToolbarAction(action: SparkQueryToolbarAction): void;
   protected isActionEnabled(action: CustomActionDefinition): boolean;
-  isStreaming: import("@angular/core").WritableSignal<boolean>;
-  private streamingSub;
-  /** Columns as sent with the stream's snapshot; empty until it arrives. */
-  protected readonly streamColumns: import("@angular/core").WritableSignal<QueryColumn[]>;
-  private readonly allItems;
-  private readonly streamItems;
-  /**
-   * Rows handed to the grid, or `null` to let it fetch for itself.
-   *
-   * Null for a normal query — an empty array would read as "here are no rows" and suppress the
-   * fetch entirely.
-   */
-  protected readonly gridData: import("@angular/core").Signal<QueryResultItem[] | null>;
   constructor();
   /**
    * The parent the URL scopes the query to (`?parentId=…&parentType=…`), sent exactly as a sub-query
@@ -138,10 +127,6 @@ export declare class SparkQueryListComponent {
   protected onCustomAction(action: CustomActionDefinition): Promise<void>;
   protected onCreate(): void;
   protected clearSearch(): void;
-  private connectStreaming;
-  private disconnectStreaming;
-  private handleStreamingMessage;
-  private applyFilter;
   static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryListComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<SparkQueryListComponent, "spark-query-list", never, {
     "extraActionsTemplate": {