@meshmakers/octo-meshboard 3.4.820 → 3.4.890

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshmakers/octo-meshboard",
-  "version": "3.4.820",
+  "version": "3.4.890",
   "peerDependencies": {
     "@angular/common": "^22.0.0",
     "@angular/core": "^22.0.0",

package/types/meshmakers-octo-meshboard.d.ts

@@ -296,18 +296,28 @@ interface PersistentQueryDataSource extends WidgetDataSource {
      * (absent/`false`) keeps the direct query.
      */
     resolutionAware?: boolean;
-    /**
-     * Optional OBIS-code filter forwarded to resolution-aware routing / the downsampling
-     * query to narrow the series (e.g. `1.8.0` active-energy import). Stream-data only.
-     */
-    obisFilter?: string;
     /**
      * Resolution-aware routing (AB#4290): the aggregation the series must be reduced with
-     * (`SUM` for additive energy, `MAX` for demand, …). Required when `resolutionAware` is on —
-     * the resolver never guesses it. Matched against a rollup's stored aggregation function; it is
-     * also the reducer applied by the downsampling query. Stream-data only.
+     * (`SUM`, `MAX`, …). Required when `resolutionAware` is on — the resolver never guesses it.
+     * Matched against a rollup's stored aggregation function; it is also the reducer applied by the
+     * downsampling query. Stream-data only.
      */
     requiredAggregation?: SeriesAggregationFunction;
+    /**
+     * Group-aggregation mode (AB#4714). Only honoured together with {@link resolutionAware}.
+     *
+     * The default resolution-aware fan-out emits ONE line per source rtId. When several sources map
+     * to the same {@link seriesGroupField} value, the widget's client-side grouping then collapses
+     * them last-write-wins, so each line reflects one arbitrary source instead of the combined value.
+     *
+     * When `true`, the source rtIds are grouped by their `seriesGroupField` attribute value FIRST,
+     * and the downsampling query runs once per group with the whole group's rtIds. The transient
+     * downsampling groups only by time bin, so it reduces (per {@link requiredAggregation}) over
+     * every source in the group server-side — one aggregate line per distinct group value. The
+     * grouping is resolved from the source entities' attributes (a rollup archive does not carry the
+     * grouping column). Stream-data only.
+     */
+    aggregateSeriesByGroup?: boolean;
 }
 /**
  * The canonical aggregation functions a resolution-aware series can be reduced with
@@ -2821,11 +2831,23 @@ declare class QueryExecutorService {
     /**
      * Best-effort per-series labels for resolution-aware fan-out (AB#4290): reads each source
      * entity's attribute matching `labelField` (canonical, case/underscore-insensitive so an archive
-     * column like `obis_code` maps to the CK attribute `obisCode`). Entities that fail to load or
-     * lack the attribute are simply omitted; the caller falls back to the rtId. Returns a
-     * `rtId → label` map.
+     * column name maps to its CK attribute). Entities that fail to load or lack the attribute are
+     * simply omitted; the caller falls back to the rtId. Returns a `rtId → label` map.
      */
     fetchSeriesLabels(ckTypeId: string, rtIds: string[], labelField: string): Promise<Map<string, string>>;
+    /** Cap on the source-entity population read for group-aggregation (AB#4714). A truncated read is
+     *  logged, never silent. */
+    private static readonly ENTITY_GROUP_FETCH_CAP;
+    /**
+     * Group-aggregation source resolution (AB#4714): fetches the source entities of `ckTypeId` in a
+     * single bulk read and buckets their rtIds by the value of `groupField` (canonical match — case
+     * and non-alphanumerics are ignored, so an archive column name maps to its CK attribute). Returns
+     * `groupValue → rtIds`. Optionally restricted to `restrictRtIds` (an entity-selector scope) —
+     * entities outside that set are dropped. Entities whose group attribute is missing/null are
+     * omitted (they cannot be attributed to a line). The population is bounded to
+     * {@link ENTITY_GROUP_FETCH_CAP}; a truncated read is logged (never silently capped).
+     */
+    fetchEntityGroups(ckTypeId: string, groupField: string, restrictRtIds?: string[]): Promise<Map<string, string[]>>;
     private buildStreamDataArg;
     private mapColumns;
     private mapRuntimeRows;
@@ -4396,12 +4418,27 @@ declare class LineChartWidgetComponent implements DashboardWidget<LineChartWidge
     private loadData;
     /**
      * Resolution-aware routing (AB#4290): resolve the best archive/rollup for the window + target
-     * point count, then downsample each source series against it. The transient downsampling groups
-     * by bin (merging source rtIds), so this fans out one call per source rtId to keep each register
-     * a separate line; each series' bins are reshaped onto the widget's configured value/series
-     * fields so the shared {@link processData} pipeline renders them unchanged.
+     * point count, then downsample the source series against it. Two fan-out shapes, both reshaped
+     * onto the widget's value/series fields so the shared {@link processData} pipeline renders them
+     * unchanged:
+     * - default: one call per source rtId → one line per register ({@link loadPerRtIdRows}).
+     * - `aggregateSeriesByGroup` (AB#4714): one call per `seriesGroupField` value with the whole
+     *   group's rtIds → one server-side-summed line per group ({@link loadGroupAggregatedRows}).
      */
     private loadResolutionAware;
+    /**
+     * Group-aggregation fan-out (AB#4714): buckets the source entities by `seriesGroupField` and runs
+     * one downsampling call per group with the group's rtIds. The transient downsampling reduces over
+     * the group's members server-side, yielding one aggregate line per distinct group value. Falls
+     * back to a single merged series when no group can be resolved.
+     */
+    private loadGroupAggregatedRows;
+    /**
+     * Default resolution-aware fan-out (AB#4290): one downsampling call per source rtId so each
+     * register stays its own line, labeled from its `seriesGroupField` attribute. With no source
+     * scope a single merged series is produced (labeled by the series-group field name).
+     */
+    private loadPerRtIdRows;
     /**
      * Reshapes one downsampling bin onto the widget's configured value + series-group fields so the
      * shared {@link processData} path plots it. The transient row carries the reduced value under a