@mintplayer/ng-spark 22.33.0 → 22.35.0

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

@@ -0,0 +1,226 @@
+import { SparkAttributeColumnRenderer, SparkAttributeDetailRenderer, SparkAttributeRendererRegistration } from "@mintplayer/ng-spark/renderers";
+import * as i0 from "@angular/core";
+import { Provider, Type } from "@angular/core";
+import { Color } from "@mintplayer/ng-bootstrap";
+import { SparkLanguageService } from "@mintplayer/ng-spark/services";
+import { EntityAttributeDefinition, PersistentObject, TranslatedString } from "@mintplayer/ng-spark/models";
+import { SparkDetailContext } from "@mintplayer/ng-spark/panels";
+/** How a dashboard value is written: a plain number, bytes (binary units), a percentage, a date, or as is. */
+export type SparkDashboardFormat = 'number' | 'bytes' | 'percent' | 'date' | 'datetime' | 'text';
+/** A finite number from a wire value (a number or a numeric string), else null. */
+export declare function toSparkNumber(value: unknown): number | null;
+/** 1536 → "1.5 KB": binary units, one decimal from KB up; "—" for no value. */
+export declare function formatSparkBytes(bytes: number | null | undefined, locale?: string): string;
+/**
+ * A value as a dashboard writes it: "—" for none; numbers by `format` (`decimals` places for `number`/`percent`,
+ * default 0); dates in the viewer's locale; anything else as text.
+ */
+export declare function formatSparkDashboardValue(value: unknown, format: SparkDashboardFormat | undefined, locale?: string, decimals?: number): string;
+/** The colour a threshold gives a value: `danger` at or past `danger`, `warning` at or past `warning`, else none. */
+export declare function sparkThresholdColor(value: number | null, thresholds: {
+  warning?: number;
+  danger?: number;
+  direction?: 'above' | 'below';
+}): 'warning' | 'danger' | null;
+/** `rendererOptions` of the `spark-stat` renderer. Every member is optional. */
+export interface SparkStatOptions {
+  /** How the value is written. Default `'number'`. */
+  format?: SparkDashboardFormat;
+  /** Decimals for `number` (default 0) and `percent` (default 1). */
+  decimals?: number;
+  /** Text after the value, e.g. `' sites'`. Default none. */
+  suffix?: string;
+  /** The value turns amber at or past this. */
+  warning?: number;
+  /** The value turns red at or past this. */
+  danger?: number;
+  /** `'above'` (default): high is bad, as for disk use. `'below'`: low is bad, as for free space. */
+  direction?: 'above' | 'below';
+}
+/**
+ * The `spark-stat` renderer: one figure, large on a detail page (a dashboard tile) and plain in a grid cell,
+ * coloured amber or red once it passes the model's `warning` / `danger` threshold. No value draws a muted dash.
+ */
+export declare class SparkStatComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  private readonly settings;
+  protected readonly text: import("@angular/core").Signal<string>;
+  protected readonly color: import("@angular/core").Signal<"warning" | "danger" | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkStatComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkStatComponent, "spark-stat", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** `rendererOptions` of the `spark-meter` renderer. Every member is optional. */
+export interface SparkMeterOptions {
+  /** The ceiling when the value is a plain number (a value `{ value, max }` brings its own). Default 100. */
+  max?: number;
+  /** How the value and the ceiling are written. Default `'number'`. */
+  format?: SparkDashboardFormat;
+  /** Amber from this share of the ceiling, in percent. Default 75. */
+  warning?: number;
+  /** Red from this share of the ceiling, in percent. Default 90. */
+  danger?: number;
+  /** The meter's accessible name. Default `'Usage'`. */
+  label?: string;
+}
+interface MeterView {
+  value: number;
+  max: number;
+  /** The share of the ceiling, in percent (0–100), one decimal. */
+  share: number;
+  color: Color;
+  text: string;
+}
+/**
+ * The `spark-meter` renderer: how much of something is used, as a bar coloured by its share (green, amber from 75 %,
+ * red from 90 % by default) with "used of total (share)" next to it. The value is a number against the `max` option, or
+ * `{ value, max }` from the server (the dashboards package's `DashboardValues.Meter`), e.g. disk bytes used of the total.
+ * No value, or no ceiling, draws a muted dash.
+ */
+export declare class SparkMeterComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  private readonly settings;
+  protected readonly label: import("@angular/core").Signal<string>;
+  protected readonly view: import("@angular/core").Signal<MeterView | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkMeterComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkMeterComponent, "spark-meter", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** One column of a `spark-dashboard-table`. */
+export interface SparkDashboardTableColumn {
+  /** The row field. For a value that is a dictionary, its rows are `{ key, value }`. */
+  key: string;
+  /** A translation key for the header (`translations.json`), shown as is when it has no translation. Default `key`. */
+  label?: string;
+  /** How the cells are written. Numbers and bytes are right-aligned. Default: as is. */
+  format?: SparkDashboardFormat | 'boolean';
+  /** Translate each cell as `{translate}{value}` (e.g. `'seoUi.runStatus.'`), falling back to the value. */
+  translate?: string;
+}
+/** `rendererOptions` of the `spark-dashboard-table` renderer. */
+export interface SparkDashboardTableOptions {
+  /** The columns, in order. Default: the first row's fields. */
+  columns?: SparkDashboardTableColumn[];
+  /** A translation key shown when there are no rows. Default `'dashboards.empty'`. */
+  empty?: string;
+}
+interface TableCell {
+  text: string;
+  check: boolean;
+}
+/**
+ * The `spark-dashboard-table` renderer (detail pages): a dashboard value that is a list of rows, such as the
+ * RavenDB statistics' collections (D12: tables are JSON attributes). A dictionary (`{ "Completed": 3 }`) reads as
+ * rows `{ key, value }`.
+ */
+export declare class SparkDashboardTableComponent implements SparkAttributeDetailRenderer {
+  private readonly locale;
+  protected readonly lang: SparkLanguageService;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly settings: import("@angular/core").Signal<SparkDashboardTableOptions>;
+  protected readonly rows: import("@angular/core").Signal<Record<string, unknown>[]>;
+  protected readonly columns: import("@angular/core").Signal<SparkDashboardTableColumn[]>;
+  protected readonly cells: import("@angular/core").Signal<TableCell[][]>;
+  protected header(column: SparkDashboardTableColumn): string;
+  protected isNumeric(column: SparkDashboardTableColumn | undefined): boolean;
+  private cell;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkDashboardTableComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkDashboardTableComponent, "spark-dashboard-table", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** The rows of a table value: a list of objects as is, a dictionary as `{ key, value }` rows, anything else none. */
+export declare function toSparkTableRows(value: unknown): Record<string, unknown>[];
+/** The `metadata` key a dashboard carries (the dashboards package's `SparkDashboardActions.MetadataKey`). */
+export declare const SPARK_DASHBOARD_METADATA_KEY = "dashboard";
+/** Whether `item` is a dashboard: the server marks one with `metadata.dashboard`. */
+export declare function isSparkDashboard(item: PersistentObject | null | undefined): boolean;
+interface DashboardTile {
+  attribute: EntityAttributeDefinition;
+  /** Columns spanned: 1, 2, or the whole row. */
+  span: 1 | 2 | 'row';
+  component: Type<any> | null;
+  inputs: Record<string, any>;
+  /** The value as text, for an attribute without a detail renderer. */
+  text: string;
+}
+interface DashboardSection {
+  id: string;
+  name: string | null;
+  label?: TranslatedString;
+  tiles: DashboardTile[];
+}
+/**
+ * The dashboard tile layout (D12): replaces a dashboard's attribute cards on the routed detail page
+ * (`SPARK_DETAIL_LAYOUTS`, registered by `provideSparkDashboards()`). Each group of the model is a section, each
+ * attribute a tile: its label above its detail renderer (`spark-stat`, `spark-meter`, `spark-trend`,
+ * `spark-dashboard-table`, …) or its plain value. `columnSpan` 2 takes two columns, 3 and more (and a table without one) the
+ * whole row. An attribute the caller may not read is not on the object and has no tile. The page follows the object
+ * over `/spark/live` like any live type, so the tiles change in place.
+ */
+export declare class SparkDashboardComponent {
+  private readonly locale;
+  private readonly renderers;
+  readonly context: import("@angular/core").InputSignal<SparkDetailContext>;
+  protected readonly sections: import("@angular/core").Signal<DashboardSection[]>;
+  /** When the server read the values, in the viewer's locale. */
+  protected readonly generatedAt: import("@angular/core").Signal<string | null>;
+  private tile;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkDashboardComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkDashboardComponent, "spark-dashboard", never, {
+    "context": {
+      "alias": "context";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The dashboard renderers under their model names. Renderers are one list, so add these to the app's own in its
+ * single `provideSparkAttributeRenderers` (or `provideSparkScoreRenderers`, which `spark-trend` comes from) call:
+ *
+ * @example
+ * provideSparkScoreRenderers([...appRenderers, ...sparkDashboardRenderers]),
+ * provideSparkDashboards(),
+ */
+export declare const sparkDashboardRenderers: readonly SparkAttributeRendererRegistration[];
+/**
+ * Draws every dashboard (an object the server marks with `metadata.dashboard`, the dashboards package's live virtual
+ * types) with the tile layout instead of the attribute cards, on the routed detail page. The renderers are registered
+ * separately: see {@link sparkDashboardRenderers}.
+ */
+export declare function provideSparkDashboards(): Provider[];

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

@@ -119,6 +119,22 @@ export interface SparkQueryRowAction {
 export declare const SPARK_QUERY_ROW_ACTIONS: InjectionToken<SparkQueryRowAction[]>;
 /** Registers grid row actions (multi — every call adds). */
 export declare function provideSparkQueryRowActions(...actions: SparkQueryRowAction[]): Provider[];
+/**
+ * A layout that draws a detail page's attributes in place of the tabs and cards (#504), for objects it
+ * `matches`: Dashboards' tile layout for objects carrying `metadata.dashboard`. It must declare
+ * `context = input.required<SparkDetailContext>()`. The action bar, sub-queries, the extra content
+ * template and the detail panels stay; the first matching layout wins.
+ */
+export interface SparkDetailLayout {
+  id: string;
+  component: Type<unknown>;
+  /** Whether this layout draws `item`. Called on every change of the object, so keep it cheap. */
+  matches(item: PersistentObject, entityType: EntityType): boolean;
+}
+/** Multi-provider: layouts that replace the attribute cards of the routed detail page for the objects they match. */
+export declare const SPARK_DETAIL_LAYOUTS: InjectionToken<SparkDetailLayout[]>;
+/** Registers detail layouts (multi — every call adds). */
+export declare function provideSparkDetailLayouts(...layouts: SparkDetailLayout[]): Provider[];
 /** Multi-provider: panels under the attributes of the routed detail page. */
 export declare const SPARK_DETAIL_PANELS: InjectionToken<SparkDetailPanel[]>;
 /** Multi-provider: extra buttons in the routed detail page's action bar. */

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

@@ -23,6 +23,7 @@ export declare class SparkPoDetailComponent {
    */
   protected readonly detailPanels: import("@mintplayer/ng-spark/panels").SparkDetailPanel[];
   protected readonly detailActions: import("@mintplayer/ng-spark/panels").SparkDetailAction[];
+  private readonly detailLayouts;
   showCustomActions: import("@angular/core").InputSignal<boolean>;
   extraActionsTemplate: import("@angular/core").InputSignal<TemplateRef<void> | null>;
   extraContentTemplate: import("@angular/core").InputSignal<TemplateRef<{
@@ -86,6 +87,8 @@ export declare class SparkPoDetailComponent {
   protected readonly isDeletedView: import("@angular/core").Signal<boolean>;
   /** What every add-on panel and action receives; rebuilt whenever the object or rights change. */
   protected readonly detailContext: import("@angular/core").Signal<SparkDetailContext | null>;
+  /** The registered layout that draws this object's attributes instead of the tabs (#504), if one matches. */
+  protected readonly detailLayout: import("@angular/core").Signal<import("@mintplayer/ng-spark/panels").SparkDetailLayout | null>;
   /**
    * The actions actually offered for the object on screen.
    *