@c8y/tutorial 1023.53.0 → 1023.57.0

package/cumulocity.config.ts

@@ -892,6 +892,13 @@ export default {
         description: 'This is an example for the countdown component.',
         scope: 'self'
       },
+      {
+        name: 'Charts',
+        module: 'ChartsExampleModule',
+        path: './src/c8y-charts/charts-example.module.ts',
+        description: 'This is an example for the charts component.',
+        scope: 'self'
+      },
       {
         name: 'Bottom drawer',
         module: 'bottomDrawerExampleModuleProviders',

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@c8y/tutorial",
-  "version": "1023.53.0",
+  "version": "1023.57.0",
   "description": "This package is used to scaffold a tutorial for Cumulocity IoT Web SDK which explains a lot of concepts.",
   "dependencies": {
-    "@c8y/style": "1023.53.0",
-    "@c8y/ngx-components": "1023.53.0",
-    "@c8y/client": "1023.53.0",
-    "@c8y/bootstrap": "1023.53.0",
+    "@c8y/style": "1023.57.0",
+    "@c8y/ngx-components": "1023.57.0",
+    "@c8y/client": "1023.57.0",
+    "@c8y/bootstrap": "1023.57.0",
     "@angular/cdk": "^20.2.14",
     "monaco-editor": "~0.53.0",
     "ngx-bootstrap": "20.0.2",
@@ -14,8 +14,8 @@
     "rxjs": "7.8.2"
   },
   "devDependencies": {
-    "@c8y/options": "1023.53.0",
-    "@c8y/devkit": "1023.53.0"
+    "@c8y/options": "1023.57.0",
+    "@c8y/devkit": "1023.57.0"
   },
   "peerDependencies": {
     "@angular/common": ">=20 <21"

package/src/__mocks/global-mocks/measurements.interceptor.ts

@@ -21,6 +21,10 @@ export class MeasurementsInterceptor implements HttpInterceptor {
   }
 
   private mockGET(_requestDescriptor: string) {
+    if (_requestDescriptor.includes('measurement/measurements/series')) {
+      return this.mockSeriesGET(_requestDescriptor);
+    }
+
     const responseGenerators = this.getResponseGenerators();
 
     for (const urlPart in responseGenerators) {
@@ -34,6 +38,72 @@ export class MeasurementsInterceptor implements HttpInterceptor {
     return null;
   }
 
+  private mockSeriesGET(_requestDescriptor: string) {
+    const jsonMatch = _requestDescriptor.match(/series(.*)$/);
+
+    if (!jsonMatch || !jsonMatch[1]) {
+      return null;
+    }
+
+    let params: any = {};
+    try {
+      params = JSON.parse(jsonMatch[1]);
+    } catch (e) {
+      console.error('Failed to parse series params', e);
+      return null;
+    }
+
+    const { dateFrom, dateTo, series } = params;
+
+    if (!dateFrom || !dateTo) {
+      return null;
+    }
+
+    const start = new Date(dateFrom);
+    const end = new Date(dateTo);
+    const values: Record<string, { min: number; max: number }[]> = {};
+
+    const current = new Date(start);
+    current.setMinutes(0, 0, 0);
+
+    while (current <= end) {
+      const timestamp = current.toISOString();
+
+      const baseValue = 50 + Math.sin(current.getTime() / (1000 * 60 * 60 * 6)) * 30;
+      const variation = Math.random() * 20 - 10;
+      const value = Math.max(0, Math.min(100, baseValue + variation));
+
+      values[timestamp] = [
+        {
+          min: Number(value.toFixed(2)),
+          max: Number(value.toFixed(2))
+        }
+      ];
+
+      current.setHours(current.getHours() + 1);
+    }
+
+    let seriesInfo = {
+      unit: '%',
+      name: 'Battery',
+      type: 'c8y_Battery'
+    };
+
+    if (series?.includes('c8y_Temperature')) {
+      seriesInfo = {
+        unit: '°C',
+        name: 'T',
+        type: 'c8y_Temperature'
+      };
+    }
+
+    return generateResponse(() => ({
+      values,
+      series: [seriesInfo],
+      truncated: false
+    }));
+  }
+
   private getResponseGenerators() {
     return {
       c8y_Battery: () => ({

package/src/c8y-charts/charts-example.component.html

@@ -0,0 +1,206 @@
+<div class="container-fluid">
+  <div class="row m-t-16">
+    <div class="col-lg-12">
+      <div class="card">
+        <div class="card-header">
+          <h3 class="card-title">Example Configurations</h3>
+        </div>
+        <div class="card-block">
+          <div
+            class="btn-group"
+            role="group"
+          >
+            @for (example of configExamples; track example.value) {
+              <button
+                class="btn"
+                [class.btn-primary]="selectedExample === example.value"
+                [class.btn-default]="selectedExample !== example.value"
+                type="button"
+                (click)="loadExampleConfiguration(example.value)"
+              >
+                {{ example.label }}
+              </button>
+            }
+          </div>
+
+          <div class="m-t-16">
+            @switch (selectedExample) {
+              @case ('basic') {
+                <div class="alert alert-info">
+                  <strong>Basic Chart:</strong>
+                  Simple chart with 2 datapoints showing temperature data over the last 24 hours.
+                  Good starting point for understanding the component.
+                </div>
+              }
+              @case ('slider') {
+                <div class="alert alert-info">
+                  <strong>With Slider:</strong>
+                  Chart with navigation slider enabled for exploring 7 days of data. Supports data
+                  aggregation and zoom capabilities.
+                </div>
+              }
+              @case ('multiaxis') {
+                <div class="alert alert-info">
+                  <strong>Multiple Axes:</strong>
+                  Chart displaying 4 datapoints with different units, each with its own Y-axis.
+                  Shows how to handle heterogeneous data types.
+                </div>
+              }
+            }
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="row m-t-16">
+    <div class="col-lg-9">
+      <div class="card">
+        <div class="card-header">
+          <h3 class="card-title">Chart Visualization</h3>
+          <span class="card-header-actions">
+            <span class="badge">Active datapoints: {{ activeDatapoints.length }}</span>
+          </span>
+        </div>
+        <div
+          class="card-block"
+          style="height: 500px"
+        >
+          <c8y-charts
+            [config]="config"
+            [alerts]="alerts"
+            [chartViewContext]="chartViewContext"
+            (updateAlarmsAndEvents)="updateAlarmsAndEvents($event)"
+            (configChangeOnZoomOut)="onSliderZoom($event)"
+            (datapointOutOfSync)="handleDatapointOutOfSync($event)"
+            (timeRangeChangeOnRealtime)="updateTimeRangeOnRealtime($event)"
+            (isMarkedAreaEnabled)="onMarkedAreaEnabled($event)"
+            (updateActiveDatapoints)="updateActiveDatapoints($event)"
+            (updateAggregatedSliderDatapoint)="updateAggregatedSliderDatapoint($event)"
+          ></c8y-charts>
+        </div>
+      </div>
+    </div>
+
+    <div class="col-lg-3">
+      <div class="card">
+        <div class="card-header">
+          <h3 class="card-title">Chart Options</h3>
+        </div>
+        <div class="card-block">
+          <fieldset class="c8y-fieldset">
+            <legend>Display Options</legend>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.yAxisSplitLines"
+                (change)="toggleOption('yAxisSplitLines')"
+              />
+              <span></span>
+              <span>Y-axis helper lines</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.xAxisSplitLines"
+                (change)="toggleOption('xAxisSplitLines')"
+              />
+              <span></span>
+              <span>X-axis helper lines</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.showSlider"
+                (change)="toggleOption('showSlider')"
+              />
+              <span></span>
+              <span>Show slider</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.smoothLines"
+                (change)="toggleOption('smoothLines')"
+              />
+              <span></span>
+              <span>Smooth lines</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.showLabelAndUnit"
+                (change)="toggleOption('showLabelAndUnit')"
+              />
+              <span></span>
+              <span>Show labels & units</span>
+            </label>
+          </fieldset>
+
+          <fieldset class="c8y-fieldset m-t-16">
+            <legend>Axis Options</legend>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.mergeMatchingDatapoints"
+                (change)="toggleOption('mergeMatchingDatapoints')"
+              />
+              <span></span>
+              <span>Merge matching datapoints</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.forceMergeDatapoints"
+                (change)="toggleOption('forceMergeDatapoints')"
+              />
+              <span></span>
+              <span>Force merge all datapoints</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.setYaxisStartToZero"
+                (change)="toggleOption('setYaxisStartToZero')"
+              />
+              <span></span>
+              <span>Y-axis starts at 0</span>
+            </label>
+          </fieldset>
+
+          <fieldset class="c8y-fieldset m-t-16">
+            <legend>Alarms & Events</legend>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.displayMarkedLine"
+                (change)="toggleOption('displayMarkedLine')"
+              />
+              <span></span>
+              <span>Show vertical lines</span>
+            </label>
+
+            <label class="c8y-checkbox">
+              <input
+                type="checkbox"
+                [checked]="config.displayMarkedPoint"
+                (change)="toggleOption('displayMarkedPoint')"
+              />
+              <span></span>
+              <span>Show icons</span>
+            </label>
+          </fieldset>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

package/src/c8y-charts/charts-example.component.ts

@@ -0,0 +1,379 @@
+import { Component, OnInit, ViewChild } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+import {
+  CoreModule,
+  DynamicComponentAlert,
+  DynamicComponentAlertAggregator,
+  WidgetTimeContextDateRangeService,
+  DateAndTimeOptions
+} from '@c8y/ngx-components';
+import { TimeContextComponent } from '@c8y/ngx-components/time-context';
+import {
+  AlarmOrEventExtended,
+  CHART_VIEW_CONTEXT,
+  ChartAlarmsService,
+  ChartEventsService,
+  ChartHelpersService,
+  ChartsComponent,
+  DatapointsGraphKPIDetails,
+  DatapointsGraphWidgetConfig
+} from '@c8y/ngx-components/echart';
+import { aggregationType } from '@c8y/client';
+
+/**
+ * This example demonstrates how to use the c8y-charts component to display
+ * time-series data with datapoints, alarms, and events.
+ *
+ * The c8y-charts component is a powerful visualization tool that:
+ * - Displays multiple datapoint series on a chart
+ * - Supports real-time data updates
+ * - Shows alarms and events as markers
+ * - Provides zoom and pan capabilities
+ * - Supports data aggregation and slider navigation
+ *
+ * Key features demonstrated:
+ * - Basic chart configuration
+ * - Handling chart events (zoom, datapoint updates)
+ * - Working with alerts and notifications
+ * - Chart view context management
+ */
+@Component({
+  selector: 'app-charts-example',
+  templateUrl: './charts-example.component.html',
+  standalone: true,
+  imports: [CommonModule, CoreModule, FormsModule, ChartsComponent],
+  providers: [
+    ChartEventsService,
+    ChartAlarmsService,
+    ChartHelpersService,
+    WidgetTimeContextDateRangeService
+  ]
+})
+export class ChartsExampleComponent implements OnInit {
+  // Chart configuration object
+  config: DatapointsGraphWidgetConfig = {
+    datapoints: [],
+    alarmsEventsConfigs: [],
+    dateFrom: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // 24 hours ago
+    dateTo: new Date().toISOString(),
+    interval: 'custom',
+    realtime: false,
+    yAxisSplitLines: true,
+    xAxisSplitLines: false,
+    showLabelAndUnit: true,
+    showSlider: true,
+    smoothLines: false,
+    displayMarkedLine: true,
+    displayMarkedPoint: true,
+    mergeMatchingDatapoints: false,
+    forceMergeDatapoints: false,
+    setYaxisStartToZero: false,
+    numberOfDecimalPlaces: 2
+  };
+
+  // Alert aggregator for chart notifications
+  alerts = new DynamicComponentAlertAggregator();
+
+  // Chart view context - determines the chart behavior and features
+  chartViewContext = CHART_VIEW_CONTEXT.DATAPOINT_EXPLORER;
+
+  // Active datapoints currently visible in the chart
+  activeDatapoints: DatapointsGraphKPIDetails[] = [];
+
+  // Time context reference
+  @ViewChild('timeContext') timeContext: TimeContextComponent;
+
+  // Time properties for binding to time context
+  timeProps: {
+    dateFrom: Date;
+    dateTo: Date;
+    interval?: string;
+    realtime?: boolean;
+    aggregation?: aggregationType | null;
+  };
+
+  // Time picker configuration
+  readonly TIME_PICKER_CONFIG: DateAndTimeOptions = {
+    showMinutes: true,
+    showSeconds: true,
+    showSpinners: false
+  };
+
+  // Flag to skip onTimeContextChange during zoom handling
+  private isHandlingZoom = false;
+
+  // Configuration examples
+  configExamples = [
+    { label: 'Basic Chart', value: 'basic' },
+    { label: 'With Slider', value: 'slider' },
+    { label: 'Multiple Axes', value: 'multiaxis' }
+  ];
+
+  selectedExample = 'basic';
+
+  ngOnInit(): void {
+    // Initialize with a basic configuration
+    this.loadExampleConfiguration('basic');
+
+    // Initialize timeProps from config
+    if (this.config.dateFrom && this.config.dateTo) {
+      this.timeProps = {
+        dateFrom: new Date(this.config.dateFrom),
+        dateTo: new Date(this.config.dateTo),
+        interval: this.config.interval as any,
+        realtime: this.config.realtime,
+        aggregation: this.config.realtime ? null : this.config.aggregation
+      };
+    }
+  }
+
+  /**
+   * Load different example configurations to demonstrate various chart capabilities
+   */
+  loadExampleConfiguration(example: string): void {
+    this.selectedExample = example;
+
+    switch (example) {
+      case 'basic':
+        this.loadBasicExample();
+        break;
+      case 'realtime':
+        this.loadRealtimeExample();
+        break;
+      case 'slider':
+        this.loadSliderExample();
+        break;
+      case 'multiaxis':
+        this.loadMultiAxisExample();
+        break;
+    }
+  }
+
+  /**
+   * Handle zoom events from the chart
+   */
+  onSliderZoom(timeProps: { dateFrom: Date; dateTo: Date; interval?: 'hours' | 'weeks' }): void {
+    this.isHandlingZoom = true;
+
+    const dateFrom = timeProps.dateFrom.toISOString();
+    const dateTo = timeProps.dateTo.toISOString();
+    const interval = timeProps.interval || 'custom';
+
+    if (
+      this.config.dateFrom === dateFrom &&
+      this.config.dateTo === dateTo &&
+      this.config.interval === interval &&
+      this.config.realtime === false
+    ) {
+      this.isHandlingZoom = false;
+      return;
+    }
+
+    // Update config
+    this.config = {
+      ...this.config,
+      dateFrom,
+      dateTo,
+      interval,
+      realtime: false,
+      isAutoRefreshEnabled: false,
+      refreshInterval: 0
+    };
+
+    // Update timeProps binding
+    this.timeProps = {
+      dateFrom: new Date(timeProps.dateFrom.getTime()),
+      dateTo: new Date(timeProps.dateTo.getTime()),
+      interval: 'custom',
+      realtime: false
+    };
+
+    this.isHandlingZoom = false;
+  }
+
+  /**
+   * Handle real-time updates to the time range
+   */
+  updateTimeRangeOnRealtime(
+    timeRange: Pick<DatapointsGraphWidgetConfig, 'dateFrom' | 'dateTo'>
+  ): void {
+    if (this.config.dateFrom === timeRange.dateFrom && this.config.dateTo === timeRange.dateTo) {
+      return;
+    }
+
+    this.config = {
+      ...this.config,
+      ...timeRange
+    };
+
+    // Update timeProps for time context
+    if (timeRange.dateFrom && timeRange.dateTo) {
+      this.timeProps = {
+        ...this.timeProps,
+        dateFrom: new Date(timeRange.dateFrom),
+        dateTo: new Date(timeRange.dateTo)
+      };
+    }
+  }
+
+  /**
+   * Handle datapoint synchronization issues
+   */
+  handleDatapointOutOfSync(datapoint: DatapointsGraphKPIDetails): void {
+    console.warn('Datapoint out of sync:', datapoint);
+
+    const alert = new DynamicComponentAlert({
+      type: 'warning',
+      text: 'Datapoint out of sync: ' + datapoint.label
+    });
+
+    this.alerts?.addAlerts(alert);
+  }
+
+  /**
+   * Update alarms and events displayed on the chart
+   */
+  updateAlarmsAndEvents(alarmsEventsConfigs: AlarmOrEventExtended[]): void {
+    if (this.config.alarmsEventsConfigs === alarmsEventsConfigs) {
+      return;
+    }
+
+    this.config = {
+      ...this.config,
+      alarmsEventsConfigs
+    };
+  }
+
+  /**
+   * Track which datapoints are currently active and visible
+   */
+  updateActiveDatapoints(activeDatapoints: DatapointsGraphKPIDetails[]): void {
+    this.activeDatapoints = activeDatapoints;
+    console.log('Active datapoints:', activeDatapoints.length);
+  }
+
+  /**
+   * Handle marked area state changes (when alarms are clicked)
+   */
+  onMarkedAreaEnabled(isEnabled: boolean): void {
+    console.log('Marked area enabled:', isEnabled);
+  }
+
+  /**
+   * Handle aggregated slider datapoint selection
+   */
+  updateAggregatedSliderDatapoint(selectedDatapoint: any): void {
+    console.log('Aggregated slider datapoint updated:', selectedDatapoint);
+  }
+
+  /**
+   * Toggle a configuration option
+   */
+  toggleOption(option: keyof DatapointsGraphWidgetConfig): void {
+    this.config = {
+      ...this.config,
+      [option]: !this.config[option]
+    };
+  }
+
+  /**
+   * Basic chart example with simple configuration
+   */
+  private loadBasicExample(): void {
+    this.config = {
+      ...this.config,
+      datapoints: this.createSampleDatapoints(2),
+      dateFrom: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+      dateTo: new Date().toISOString(),
+      interval: 'custom',
+      realtime: false,
+      showSlider: false,
+      yAxisSplitLines: true,
+      xAxisSplitLines: false
+    };
+  }
+
+  /**
+   * Real-time chart example with auto-refresh
+   */
+  private loadRealtimeExample(): void {
+    this.config = {
+      ...this.config,
+      datapoints: this.createSampleDatapoints(1),
+      dateFrom: new Date(Date.now() - 60 * 60 * 1000).toISOString(), // 1 hour ago
+      dateTo: new Date().toISOString(),
+      interval: 'hours',
+      realtime: true,
+      isAutoRefreshEnabled: true,
+      refreshInterval: 5000,
+      showSlider: false
+    };
+  }
+
+  /**
+   * Chart with slider for data exploration
+   */
+  private loadSliderExample(): void {
+    this.config = {
+      ...this.config,
+      datapoints: this.createSampleDatapoints(3),
+      dateFrom: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days ago
+      dateTo: new Date().toISOString(),
+      interval: 'weeks',
+      realtime: false,
+      showSlider: true,
+      aggregation: aggregationType.HOURLY
+    };
+  }
+
+  /**
+   * Chart with multiple Y-axes for different data types
+   */
+  private loadMultiAxisExample(): void {
+    this.config = {
+      ...this.config,
+      datapoints: this.createSampleDatapoints(4, true),
+      dateFrom: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+      dateTo: new Date().toISOString(),
+      interval: 'custom',
+      realtime: false,
+      showSlider: true,
+      mergeMatchingDatapoints: false,
+      showLabelAndUnit: true
+    };
+  }
+
+  /**
+   * Create sample datapoints for demonstration
+   * In a real application, these would come from your device/asset data
+   */
+  private createSampleDatapoints(count: number, variedUnits = false): DatapointsGraphKPIDetails[] {
+    const datapoints: DatapointsGraphKPIDetails[] = [];
+    const units = variedUnits ? ['°C', '%', 'kWh', 'bar'] : ['°C'];
+
+    for (let i = 0; i < count; i++) {
+      datapoints.push({
+        __target: { id: `device${i + 1}`, name: `Device ${i + 1}` },
+        fragment: 'c8y_Battery',
+        series: '%',
+        label: `Temperature ${i + 1}`,
+        unit: units[i % units.length],
+        color: this.getColorForIndex(i),
+        lineType: 'line',
+        renderType: 'min',
+        __active: true
+      } as any);
+    }
+
+    return datapoints;
+  }
+
+  /**
+   * Get a color for a datapoint based on its index
+   */
+  private getColorForIndex(index: number): string {
+    const colors = ['#1776BF', '#14A68E', '#F3B511', '#E66C37', '#9D5BBA'];
+    return colors[index % colors.length];
+  }
+}

package/src/c8y-charts/charts-example.module.ts

@@ -0,0 +1,20 @@
+import { NgModule } from '@angular/core';
+import { NavigatorNode, hookNavigator, hookRoute } from '@c8y/ngx-components';
+
+@NgModule({
+  providers: [
+    hookRoute({
+      path: 'chart-example',
+      loadComponent: () => import('./charts-example.component').then(m => m.ChartsExampleComponent)
+    }),
+    hookNavigator(
+      new NavigatorNode({
+        path: '/chart-example',
+        label: 'Chart Example',
+        icon: 'combo-chart',
+        priority: 115
+      })
+    )
+  ]
+})
+export class ChartsExampleModule {}

package/src/hooks/service/counter/counter.model.ts

@@ -14,6 +14,8 @@ export interface ICounterService {
   count: () => void;
 }
 
+export {};
+
 declare global {
   /**
    * The `CumulocityServiceRegistry` namespaces is declared in `@c8y/ngx-components` as part of the global scope.

package/src/modal/confirm-modal/confirm-modal-example.component.ts

@@ -17,6 +17,11 @@ import { DeleteModalExampleComponent } from './delete-modal-example.component';
         Confirm modal using <code>c8y-confirm-modal</code> component
       </button>
     </div>
+    <div class="p-b-24 text-center">
+      <button class="btn btn-default" (click)="deleteTenantWithCodeVerification()">
+        Confirm modal with code verification
+      </button>
+    </div>
   </div>`,
   standalone: true,
   imports: [ModalModule, FormsModule, CoreModule]
@@ -69,4 +74,25 @@ export class ConfirmModalExampleComponent {
       console.log('Cancel clicked');
     }
   }
+
+  async deleteTenantWithCodeVerification() {
+    try {
+      await this.modalService.confirm(
+        'Confirm delete?',
+        'You are about to delete the tenant. This action will immediately affect all users.<br><br>For security reasons, enter the following code to continue:',
+        Status.DANGER,
+        {
+          ok: 'Delete'
+        },
+        {},
+        undefined,
+        true // requireCodeVerification
+      );
+      // eslint-disable-next-line no-console
+      console.log('Delete confirmed with code verification');
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.log('Cancel clicked or code verification failed');
+    }
+  }
 }