32884 analytics dashboard refactor state (dotCMS#33030)

### Proposed Changes

This pull request refactors and standardizes how time ranges are handled
throughout the Dot Analytics data access layer. The main improvements
include centralizing time range constants, updating types and services
to use these new constants, and enhancing granularity calculation for
custom date ranges. It also updates UI components and tests to align
with these changes.

**Time Range Standardization and Refactoring**
- Introduced `TIME_RANGE_OPTIONS` and `TIME_RANGE_CUBEJS_MAPPING`
constants for consistent time range handling across the codebase,
replacing hardcoded strings and scattered definitions.
[[1]](diffhunk://#diff-0d3fae337a838afd84911fc8b3587e656c3c8ddc1e2b3f96bcd4113d9782aa89R1-R15)
[[2]](diffhunk://#diff-9a6d064319b5b88cf3f0a012b5ca60b259eb4ee29e6c26ba78139a9a05a0f346R1)
[[3]](diffhunk://#diff-adb26a280c70da63050345af049168a8480129fb4d4e8d72796fcf6e8590b519R10-R12)
- Updated types (`TimeRange`, `TimeRangeCubeJS`, etc.) and removed
legacy time range constants, ensuring all type definitions rely on the
new centralized constants.

**Service and Store Updates**
- Refactored `DotAnalyticsService` methods to use
`TIME_RANGE_OPTIONS.last7days` as the default and to map time ranges via
a new private `#getTimeRange` method, ensuring proper Cube.js query
formatting.
[[1]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL11-R20)
[[2]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL34-R42)
[[3]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL54-R62)
[[4]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL74-R75)
[[5]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL83-R84)
[[6]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL97-R108)
[[7]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL122-R121)
[[8]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL131-R130)
[[9]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL145-R144)
[[10]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bL155-R154)
[[11]](diffhunk://#diff-c0a594cb6bf35693b60035c742263700865b55e180715509ac6b9377ddaeb95bR163-R172)
- Updated the analytics dashboard store to use the new time range
constants for initial state.
[[1]](diffhunk://#diff-e3042fd9ba0c764b3ca7c9bcb6dfc598a9ffe7a1d69f7b6696b67b6bfd4e8e0aR25)
[[2]](diffhunk://#diff-e3042fd9ba0c764b3ca7c9bcb6dfc598a9ffe7a1d69f7b6696b67b6bfd4e8e0aL46-R47)

**Granularity Calculation Enhancements**
- Improved `determineGranularityForTimeRange` utility to handle custom
date ranges more accurately, using `date-fns` to determine if the range
is within the same day, month, or spans multiple months, and returning
the appropriate granularity (`hour`, `day`, or `month`).
[[1]](diffhunk://#diff-3ca44ed41a4fb83cc93df2c0268f2f4a0d620b4a0794673bb62a5242aa26d841R1-R10)
[[2]](diffhunk://#diff-3ca44ed41a4fb83cc93df2c0268f2f4a0d620b4a0794673bb62a5242aa26d841L28-R56)
- Added comprehensive tests for custom date range granularity logic.

**UI and Testing Updates**
- Updated UI components to trigger handlers on dropdown and calendar
changes, and to use the new date format and event bindings for custom
date selection.
[[1]](diffhunk://#diff-bc8d103344262ac3136ad2bbc9dd3042b062cbb008e7fdf9eb839bf46fe7e37bR17)
[[2]](diffhunk://#diff-bc8d103344262ac3136ad2bbc9dd3042b062cbb008e7fdf9eb839bf46fe7e37bL27-R32)
- Refactored component tests to use `queryParamMap` instead of
`queryParams`, matching the updated Angular ActivatedRoute API and
aligning with new time range handling.
[[1]](diffhunk://#diff-e08307bf30a07105f6cca75ae1d9b863dc15b363e60cf35aed799ca8cfd7685dL18-R18)
[[2]](diffhunk://#diff-e08307bf30a07105f6cca75ae1d9b863dc15b363e60cf35aed799ca8cfd7685dL227-R239)
[[3]](diffhunk://#diff-e08307bf30a07105f6cca75ae1d9b863dc15b363e60cf35aed799ca8cfd7685dL253-R251)

### Checklist
- [x] Tests
- [x] Translations
- [x] Security Implications Contemplated (add notes if applicable)

### Additional Info
** any additional useful context or info **

Author: nicobytes

core-web/libs/portlets/dot-analytics/data-access/src/index.ts

@@ -7,5 +7,8 @@ export * from './lib/services/dot-analytics.service';
 // Utils
 export * from './lib/utils/data/analytics-data.utils';
 
+// Constants
+export * from './lib/constants';
+
 // Types (organized by category)
 export * from './lib/types';

core-web/libs/portlets/dot-analytics/data-access/src/lib/constants/dot-analytics.constants.ts

@@ -0,0 +1,15 @@
+export const TIME_RANGE_OPTIONS = {
+    today: 'today',
+    yesterday: 'yesterday',
+    last7days: 'last7days',
+    last30days: 'last30days',
+    custom: 'custom'
+} as const;
+
+/** Reverse mapping for Internal → URL-friendly */
+export const TIME_RANGE_CUBEJS_MAPPING = {
+    today: 'today',
+    yesterday: 'yesterday',
+    last7days: 'from 7 days ago to now',
+    last30days: 'from 30 days ago to now'
+} as const;

core-web/libs/portlets/dot-analytics/data-access/src/lib/constants/index.ts

@@ -0,0 +1 @@
+export * from './dot-analytics.constants';

core-web/libs/portlets/dot-analytics/data-access/src/lib/services/dot-analytics.service.spec.ts

@@ -2,10 +2,11 @@ import { createHttpFactory, HttpMethod, SpectatorHttp } from '@ngneat/spectator/
 
 import { DotAnalyticsService } from './dot-analytics.service';
 
-import { DEFAULT_TIME_RANGE, type TimeRange } from '../../index';
+import { TIME_RANGE_OPTIONS } from '../constants';
 
 const ANALYTICS_API_ENDPOINT = '/api/v1/analytics/content/_query/cube';
 const TEST_SITE_ID = 'test-site-123';
+const DEFAULT_TIME_RANGE = TIME_RANGE_OPTIONS.last7days;
 
 describe('DotAnalyticsService', () => {
     let spectator: SpectatorHttp<DotAnalyticsService>;
@@ -44,13 +45,16 @@ describe('DotAnalyticsService', () => {
             });
 
             it('should make POST request with custom timeRange', () => {
-                const timeRange: TimeRange = 'from 30 days ago to now';
-                spectator.service.totalPageViews(timeRange, TEST_SITE_ID).subscribe();
+                spectator.service
+                    .totalPageViews(TIME_RANGE_OPTIONS.last30days, TEST_SITE_ID)
+                    .subscribe();
 
                 const req = spectator.expectOne(ANALYTICS_API_ENDPOINT, HttpMethod.POST);
                 expect(req.request.url).toBe(ANALYTICS_API_ENDPOINT);
                 expect(req.request.body).toBeDefined();
-                expect(req.request.body.timeDimensions[0].dateRange).toBe(timeRange);
+                expect(req.request.body.timeDimensions[0].dateRange).toBe(
+                    'from 30 days ago to now'
+                );
             });
         });
 

core-web/libs/portlets/dot-analytics/data-access/src/lib/services/dot-analytics.service.ts

@@ -8,15 +8,16 @@ import { map } from 'rxjs/operators';
 import {
     AnalyticsApiResponse,
     DEFAULT_COUNT_LIMIT,
-    DEFAULT_TIME_RANGE,
     PageViewDeviceBrowsersEntity,
     PageViewTimeLineEntity,
+    TimeRangeCubeJS,
     TimeRangeInput,
     TopPagePerformanceEntity,
     TopPerformaceTableEntity,
     TotalPageViewsEntity,
     UniqueVisitorsEntity
 } from '../../index';
+import { TIME_RANGE_CUBEJS_MAPPING, TIME_RANGE_OPTIONS } from '../constants';
 import { createCubeQuery } from '../utils/cube/cube-query-builder.util';
 import { determineGranularityForTimeRange } from '../utils/data/analytics-data.utils';
 
@@ -31,14 +32,14 @@ export class DotAnalyticsService {
      * Total de pageviews en el período especificado
      */
     totalPageViews(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[]
     ): Observable<TotalPageViewsEntity> {
         const queryBuilder = createCubeQuery()
             .measures(['totalRequest'])
             .pageviews()
             .siteId(siteId)
-            .timeRange('createdAt', timeRange);
+            .timeRange('createdAt', this.#getTimeRange(timeRange));
 
         const query = queryBuilder.build();
 
@@ -51,14 +52,14 @@ export class DotAnalyticsService {
      * Visitantes únicos (sesiones únicas) en el período especificado
      */
     uniqueVisitors(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[]
     ): Observable<UniqueVisitorsEntity> {
         const queryBuilder = createCubeQuery()
             .measures(['totalUsers'])
             .pageviews()
             .siteId(siteId)
-            .timeRange('createdAt', timeRange);
+            .timeRange('createdAt', this.#getTimeRange(timeRange));
 
         const query = queryBuilder.build();
 
@@ -71,7 +72,7 @@ export class DotAnalyticsService {
      * Top page performance metric (total requests from the most visited page)
      */
     topPagePerformance(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[]
     ): Observable<TopPagePerformanceEntity> {
         const queryBuilder = createCubeQuery()
@@ -80,7 +81,7 @@ export class DotAnalyticsService {
             .pageviews()
             .siteId(siteId)
             .orderBy('totalRequest', 'desc')
-            .timeRange('createdAt', timeRange)
+            .timeRange('createdAt', this.#getTimeRange(timeRange))
             .limit(1);
 
         const query = queryBuilder.build();
@@ -94,7 +95,7 @@ export class DotAnalyticsService {
      * Get page view timeline data
      */
     pageViewTimeLine(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[]
     ): Observable<PageViewTimeLineEntity[]> {
         // Determine granularity based on specific timeRange values
@@ -104,7 +105,7 @@ export class DotAnalyticsService {
             .measures(['totalRequest'])
             .pageviews()
             .siteId(siteId)
-            .timeRange('createdAt', timeRange, granularity);
+            .timeRange('createdAt', this.#getTimeRange(timeRange), granularity);
 
         const query = queryBuilder.build();
 
@@ -117,7 +118,7 @@ export class DotAnalyticsService {
      * Pageviews by device/browser for distribution chart
      */
     pageViewDeviceBrowsers(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[]
     ): Observable<PageViewDeviceBrowsersEntity[]> {
         const queryBuilder = createCubeQuery()
@@ -126,7 +127,7 @@ export class DotAnalyticsService {
             .pageviews()
             .siteId(siteId)
             .orderBy('totalRequest', 'desc')
-            .timeRange('createdAt', timeRange)
+            .timeRange('createdAt', this.#getTimeRange(timeRange))
             .limit(DEFAULT_COUNT_LIMIT);
 
         const query = queryBuilder.build();
@@ -140,7 +141,7 @@ export class DotAnalyticsService {
      * Top pages table with title and pageviews
      */
     getTopPagePerformanceTable(
-        timeRange: TimeRangeInput = DEFAULT_TIME_RANGE,
+        timeRange: TimeRangeInput = TIME_RANGE_OPTIONS.last7days,
         siteId: string | string[],
         limit = DEFAULT_COUNT_LIMIT
     ): Observable<TopPerformaceTableEntity[]> {
@@ -150,7 +151,7 @@ export class DotAnalyticsService {
             .pageviews()
             .siteId(siteId)
             .orderBy('totalRequest', 'desc')
-            .timeRange('createdAt', timeRange)
+            .timeRange('createdAt', this.#getTimeRange(timeRange))
             .limit(limit);
 
         const query = queryBuilder.build();
@@ -159,4 +160,14 @@ export class DotAnalyticsService {
             .post<AnalyticsApiResponse<TopPerformaceTableEntity>>(this.#BASE_URL, query)
             .pipe(map((response) => response.entity));
     }
+
+    #getTimeRange(timeRange: TimeRangeInput): TimeRangeCubeJS {
+        if (Array.isArray(timeRange)) {
+            return timeRange;
+        }
+        return (
+            TIME_RANGE_CUBEJS_MAPPING[timeRange as keyof typeof TIME_RANGE_CUBEJS_MAPPING] ||
+            TIME_RANGE_CUBEJS_MAPPING.last7days
+        );
+    }
 }

core-web/libs/portlets/dot-analytics/data-access/src/lib/store/dot-analytics-dashboard.store.ts

@@ -22,6 +22,7 @@ import {
     TotalPageViewsEntity,
     UniqueVisitorsEntity
 } from '../../index';
+import { TIME_RANGE_OPTIONS } from '../constants';
 import { DotAnalyticsService } from '../services/dot-analytics.service';
 
 /**
@@ -43,7 +44,7 @@ export interface DotAnalyticsDashboardState {
  * Initial store state
  */
 const initialState: DotAnalyticsDashboardState = {
-    timeRange: 'from 7 days ago to now',
+    timeRange: TIME_RANGE_OPTIONS.last7days,
     totalPageViews: { status: ComponentStatus.INIT, data: null, error: null },
     uniqueVisitors: { status: ComponentStatus.INIT, data: null, error: null },
     topPagePerformance: { status: ComponentStatus.INIT, data: null, error: null },

core-web/libs/portlets/dot-analytics/data-access/src/lib/types/common.types.ts

@@ -4,32 +4,28 @@
 
 import { ComponentStatus } from '@dotcms/dotcms-models';
 
-/**
- * Options for predefined time ranges in analytics
- * These correspond to common analytics reporting periods
- */
-export const TimeRangeOptions = {
-    TODAY: 'today',
-    YESTERDAY: 'yesterday',
-    LAST_7_DAYS: 'from 7 days ago to now',
-    LAST_30_DAYS: 'from 30 days ago to now',
-    CUSTOM_TIME_RANGE: 'CUSTOM_TIME_RANGE'
-} as const;
-
-/**
- * Default time range for analytics queries (7 days)
- */
-export const DEFAULT_TIME_RANGE: TimeRange = TimeRangeOptions.LAST_7_DAYS;
+import {
+    TIME_RANGE_CUBEJS_MAPPING,
+    TIME_RANGE_OPTIONS
+} from '../constants/dot-analytics.constants';
 
 /**
  * Union type representing all possible time range values
  * Includes predefined ranges and custom time expressions
  */
-export type TimeRange = (typeof TimeRangeOptions)[keyof typeof TimeRangeOptions];
+export type TimeRange = (typeof TIME_RANGE_OPTIONS)[keyof typeof TIME_RANGE_OPTIONS];
 
 /** Date range for custom time period selection as ISO date strings */
 export type DateRange = [string, string];
 
+/**
+ * Union type representing all possible time range values for Cube.js
+ * Includes predefined ranges and custom time expressions
+ */
+export type TimeRangeCubeJS =
+    | (typeof TIME_RANGE_CUBEJS_MAPPING)[keyof typeof TIME_RANGE_CUBEJS_MAPPING]
+    | DateRange;
+
 /** Union type for time range inputs - supports both predefined ranges and custom date arrays */
 export type TimeRangeInput = TimeRange | DateRange;