fix(adoption-insights): Adoption Insights - 1 active users per day were conducted during this period. (#1365)

lokanandaprabhu · web-flow · commit 617de8bbf19a · 2025-09-15T16:24:12.000+05:30
* fix(adoption-insights): improve analytics text clarity by replacing 'were conducted' with professional terminology

* fix(adoption-insights): enhance grouping text support for all time periods

- Added getGroupingLabel utility function to map grouping values to proper labels
- Updated tests to verify all grouping types work correctly
diff --git a/workspaces/adoption-insights/.changeset/fix-text-wording-conducted-analytics.md b/workspaces/adoption-insights/.changeset/fix-text-wording-conducted-analytics.md
@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-adoption-insights': patch
+---
+
+- Fixed confusing text in ActiveUsers and Searches components by replacing "were conducted" with professional analytics terminology
+- Updated text to use "Average peak active user count" and "Average search count" for better clarity
+- Enhanced time period text to properly handle all grouping types (hourly, daily, weekly, monthly) instead of only supporting hour and day
diff --git a/workspaces/adoption-insights/packages/app/e2e-tests/insights.test.ts b/workspaces/adoption-insights/packages/app/e2e-tests/insights.test.ts
@@ -69,7 +69,7 @@ test('Active users panel shows 1 visitor', async () => {
   await expect(panel).toMatchAriaSnapshot(`
     - heading "Active users" [level=5]
     - button "Export CSV"
-    - paragraph: An average of 1 active users per hour were active during this period.
+    - paragraph: Average peak active user count was 1 per hour for this period.
     `);
 });
 
@@ -186,7 +186,7 @@ test.describe(() => {
     await panel.scrollIntoViewIfNeeded();
     await expect(panel.locator('.recharts-surface')).toBeVisible();
     await expect(panel).toContainText(
-      'An average of 1 searches per hour were conducted during this period.',
+      'Average search count was 1 per hour for this period.',
     );
   });
 
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/report.api.md b/workspaces/adoption-insights/plugins/adoption-insights/report.api.md
@@ -56,6 +56,8 @@ export const adoptionInsightsTranslationRef: TranslationRef<
     readonly 'activeUsers.legend.newUsers': string;
     readonly 'activeUsers.legend.returningUsers': string;
     readonly 'activeUsers.title': string;
+    readonly 'activeUsers.month': string;
+    readonly 'activeUsers.week': string;
     readonly 'activeUsers.hour': string;
     readonly 'activeUsers.day': string;
     readonly 'activeUsers.averagePrefix': string;
@@ -71,6 +73,8 @@ export const adoptionInsightsTranslationRef: TranslationRef<
     readonly 'techDocs.topNTitle': string;
     readonly 'techDocs.allTitle': string;
     readonly 'searches.title': string;
+    readonly 'searches.month': string;
+    readonly 'searches.week': string;
     readonly 'searches.hour': string;
     readonly 'searches.day': string;
     readonly 'searches.averagePrefix': string;
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/components/ActiveUsers/ActiveUsers.tsx b/workspaces/adoption-insights/plugins/adoption-insights/src/components/ActiveUsers/ActiveUsers.tsx
@@ -36,6 +36,7 @@ import {
   getXAxisformat,
   getXAxisTickValues,
   formatNumber,
+  getGroupingLabel,
 } from '../../utils/utils';
 import { useActiveUsers } from '../../hooks/useActiveUsers';
 import { Typography } from '@material-ui/core';
@@ -99,13 +100,10 @@ const ActiveUsers = () => {
                   count: Math.round(
                     getAverage(data, 'total_users'),
                   ).toLocaleString('en-US'),
-                  period:
-                    grouping === 'hourly'
-                      ? t('activeUsers.hour')
-                      : t('activeUsers.day'),
+                  period: getGroupingLabel(grouping, t, 'activeUsers'),
                 }}
               />
-            </b>{' '}
+            </b>
             {t('activeUsers.averageSuffix')}
           </Typography>
           <Box sx={{ height: 310, mt: 4, mb: 4, ml: 0, mr: 0 }}>
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/components/Searches/Searches.tsx b/workspaces/adoption-insights/plugins/adoption-insights/src/components/Searches/Searches.tsx
@@ -36,6 +36,7 @@ import {
   getXAxisformat,
   getXAxisTickValues,
   formatNumber,
+  getGroupingLabel,
 } from '../../utils/utils';
 import CustomCursor from '../Common/CustomCursor';
 import EmptyChartState from '../Common/EmptyChartState';
@@ -102,13 +103,10 @@ const Searches = () => {
                   count: Math.round(getAverage(data, 'count')).toLocaleString(
                     'en-US',
                   ),
-                  period:
-                    grouping === 'hourly'
-                      ? t('searches.hour')
-                      : t('searches.day'),
+                  period: getGroupingLabel(grouping, t, 'searches'),
                 }}
               />
-            </b>{' '}
+            </b>
             {t('searches.averageSuffix')}
           </Typography>
           <Box sx={{ height: 310, mt: 4, mb: 4, ml: 0, mr: 0 }}>
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/components/Searches/__tests__/Searches.test.tsx b/workspaces/adoption-insights/plugins/adoption-insights/src/components/Searches/__tests__/Searches.test.tsx
@@ -80,6 +80,35 @@ describe('Searches Component', () => {
 
     render(<Searches />);
     expect(screen.getByText(/300 searches/i)).toBeInTheDocument();
-    expect(screen.getByText(/150 searches per day/i)).toBeInTheDocument();
+    expect(screen.getByText(/Average search count was/i)).toBeInTheDocument();
+    expect(screen.getByText(/150 per day/i)).toBeInTheDocument();
+  });
+
+  it('should display correct time unit for different groupings', () => {
+    const testCases = [
+      { grouping: 'hourly', expectedText: '150 per hour' },
+      { grouping: 'daily', expectedText: '150 per day' },
+      { grouping: 'weekly', expectedText: '150 per week' },
+      { grouping: 'monthly', expectedText: '150 per month' },
+    ];
+
+    testCases.forEach(({ grouping, expectedText }) => {
+      (useSearches as jest.Mock).mockReturnValue({
+        searches: {
+          data: [
+            { date: '2025-03-01', count: 100 },
+            { date: '2025-03-02', count: 200 },
+          ],
+          grouping,
+        },
+        loading: false,
+      });
+
+      const { unmount } = render(<Searches />);
+      expect(
+        screen.getByText(new RegExp(expectedText, 'i')),
+      ).toBeInTheDocument();
+      unmount();
+    });
   });
 });
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/translations/de.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/translations/de.ts
@@ -36,11 +36,14 @@ const adoptionInsightsTranslationDe = createTranslationMessages({
     'header.dateRange.ok': 'OK',
     'header.dateRange.defaultLabel': 'Letzte 28 Tage',
     'activeUsers.title': 'Aktive Benutzer',
-    'activeUsers.averagePrefix': 'Im Durchschnitt',
-    'activeUsers.averageText': '{{count}} aktive Benutzer pro {{period}}',
-    'activeUsers.averageSuffix': 'waren in diesem Zeitraum aktiv.',
+    'activeUsers.averagePrefix':
+      'Durchschnittliche Spitzenanzahl aktiver Benutzer war',
+    'activeUsers.averageText': '{{count}} pro {{period}}',
+    'activeUsers.averageSuffix': ' für diesen Zeitraum.',
     'activeUsers.hour': 'Stunde',
     'activeUsers.day': 'Tag',
+    'activeUsers.week': 'Woche',
+    'activeUsers.month': 'Monat',
     'activeUsers.legend.newUsers': 'Neue Benutzer',
     'activeUsers.legend.returningUsers': 'Wiederkehrende Benutzer',
     'templates.title': 'Top-Vorlagen',
@@ -57,11 +60,13 @@ const adoptionInsightsTranslationDe = createTranslationMessages({
     'techDocs.allTitle': 'Alle TechDocs',
     'searches.title': 'Top-Suchen',
     'searches.totalCount': '{{count}} Suchen',
-    'searches.averagePrefix': 'Im Durchschnitt',
-    'searches.averageText': '{{count}} Suchen pro {{period}}',
-    'searches.averageSuffix': 'wurden in diesem Zeitraum durchgeführt.',
+    'searches.averagePrefix': 'Durchschnittliche Suchanzahl war',
+    'searches.averageText': '{{count}} pro {{period}}',
+    'searches.averageSuffix': ' für diesen Zeitraum.',
     'searches.hour': 'Stunde',
     'searches.day': 'Tag',
+    'searches.week': 'Woche',
+    'searches.month': 'Monat',
     'users.title': 'Gesamtzahl der Benutzer',
     'users.haveLoggedIn': 'haben sich angemeldet',
     'users.loggedInUsers': 'Angemeldete Benutzer',
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/translations/es.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/translations/es.ts
@@ -36,11 +36,13 @@ const adoptionInsightsTranslationEs = createTranslationMessages({
     'header.dateRange.ok': 'OK',
     'header.dateRange.defaultLabel': 'Últimos 28 días',
     'activeUsers.title': 'Usuarios Activos',
-    'activeUsers.averagePrefix': 'Un promedio de',
-    'activeUsers.averageText': '{{count}} usuarios activos por {{period}}',
-    'activeUsers.averageSuffix': 'estuvieron activos durante este período.',
+    'activeUsers.averagePrefix': 'El promedio de usuarios activos máximos fue',
+    'activeUsers.averageText': '{{count}} por {{period}}',
+    'activeUsers.averageSuffix': ' para este período.',
     'activeUsers.hour': 'hora',
     'activeUsers.day': 'día',
+    'activeUsers.week': 'semana',
+    'activeUsers.month': 'mes',
     'activeUsers.legend.newUsers': 'Nuevos usuarios',
     'activeUsers.legend.returningUsers': 'Usuarios recurrentes',
     'templates.title': 'Top plantillas',
@@ -57,11 +59,13 @@ const adoptionInsightsTranslationEs = createTranslationMessages({
     'techDocs.allTitle': 'Todos los TechDocs',
     'searches.title': 'Top búsquedas',
     'searches.totalCount': '{{count}} búsquedas',
-    'searches.averagePrefix': 'Un promedio de',
-    'searches.averageText': '{{count}} búsquedas por {{period}}',
-    'searches.averageSuffix': 'se realizaron durante este período.',
+    'searches.averagePrefix': 'El promedio de búsquedas fue',
+    'searches.averageText': '{{count}} por {{period}}',
+    'searches.averageSuffix': ' para este período.',
     'searches.hour': 'hora',
     'searches.day': 'día',
+    'searches.week': 'semana',
+    'searches.month': 'mes',
     'users.title': 'Número total de usuarios',
     'users.haveLoggedIn': 'han iniciado sesión',
     'users.loggedInUsers': 'Usuarios conectados',
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/translations/fr.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/translations/fr.ts
@@ -36,11 +36,14 @@ const adoptionInsightsTranslationFr = createTranslationMessages({
     'header.dateRange.ok': 'OK',
     'header.dateRange.defaultLabel': 'Les 28 derniers jours',
     'activeUsers.title': 'Utilisateurs Actifs',
-    'activeUsers.averagePrefix': 'En moyenne',
-    'activeUsers.averageText': '{{count}} utilisateurs actifs par {{period}}',
-    'activeUsers.averageSuffix': 'étaient actifs au cours de cette période.',
+    'activeUsers.averagePrefix':
+      "Le nombre moyen d'utilisateurs actifs en pointe était",
+    'activeUsers.averageText': '{{count}} par {{period}}',
+    'activeUsers.averageSuffix': ' pour cette période.',
     'activeUsers.hour': 'heure',
     'activeUsers.day': 'jour',
+    'activeUsers.week': 'semaine',
+    'activeUsers.month': 'mois',
     'activeUsers.legend.newUsers': 'Nouveaux utilisateurs',
     'activeUsers.legend.returningUsers': 'Utilisateurs récurrents',
     'templates.title': 'Top modèles',
@@ -57,11 +60,13 @@ const adoptionInsightsTranslationFr = createTranslationMessages({
     'techDocs.allTitle': 'Tous les TechDocs',
     'searches.title': 'Top recherches',
     'searches.totalCount': '{{count}} recherches',
-    'searches.averagePrefix': 'En moyenne',
-    'searches.averageText': '{{count}} recherches par {{period}}',
-    'searches.averageSuffix': 'ont été effectuées durant cette période.',
+    'searches.averagePrefix': 'Le nombre moyen de recherches était',
+    'searches.averageText': '{{count}} par {{period}}',
+    'searches.averageSuffix': ' pour cette période.',
     'searches.hour': 'heure',
     'searches.day': 'jour',
+    'searches.week': 'semaine',
+    'searches.month': 'mois',
     'users.title': "Nombre total d'utilisateurs",
     'users.haveLoggedIn': 'se sont connectés',
     'users.loggedInUsers': 'Utilisateurs connectés',
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/translations/it.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/translations/it.ts
@@ -36,11 +36,14 @@ const adoptionInsightsTranslationIt = createTranslationMessages({
     'header.dateRange.ok': 'OK',
     'header.dateRange.defaultLabel': 'Ultimi 28 giorni',
     'activeUsers.title': 'Utenti Attivi',
-    'activeUsers.averagePrefix': 'In media',
-    'activeUsers.averageText': '{{count}} utenti attivi per {{period}}',
-    'activeUsers.averageSuffix': 'sono stati attivi durante questo periodo.',
+    'activeUsers.averagePrefix':
+      'Il numero medio di utenti attivi di picco era',
+    'activeUsers.averageText': '{{count}} per {{period}}',
+    'activeUsers.averageSuffix': ' per questo periodo.',
     'activeUsers.hour': 'ora',
     'activeUsers.day': 'giorno',
+    'activeUsers.week': 'settimana',
+    'activeUsers.month': 'mese',
     'activeUsers.legend.newUsers': 'Nuovi utenti',
     'activeUsers.legend.returningUsers': 'Utenti di ritorno',
     'templates.title': 'Top template',
@@ -57,11 +60,13 @@ const adoptionInsightsTranslationIt = createTranslationMessages({
     'techDocs.allTitle': 'Tutti i TechDocs',
     'searches.title': 'Top ricerche',
     'searches.totalCount': '{{count}} ricerche',
-    'searches.averagePrefix': 'In media',
-    'searches.averageText': '{{count}} ricerche per {{period}}',
-    'searches.averageSuffix': 'sono state condotte durante questo periodo.',
+    'searches.averagePrefix': 'Il numero medio di ricerche era',
+    'searches.averageText': '{{count}} per {{period}}',
+    'searches.averageSuffix': ' per questo periodo.',
     'searches.hour': 'ora',
     'searches.day': 'giorno',
+    'searches.week': 'settimana',
+    'searches.month': 'mese',
     'users.title': 'Numero totale di utenti',
     'users.haveLoggedIn': 'hanno effettuato il login',
     'users.loggedInUsers': 'Utenti connessi',
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/translations/ref.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/translations/ref.ts
@@ -41,11 +41,13 @@ export const adoptionInsightsMessages = {
   },
   activeUsers: {
     title: 'Active users',
-    averagePrefix: 'An average of',
-    averageText: '{{count}} active users per {{period}}',
-    averageSuffix: 'were active during this period.',
+    averagePrefix: 'Average peak active user count was',
+    averageText: '{{count}} per {{period}}',
+    averageSuffix: ' for this period.',
     hour: 'hour',
     day: 'day',
+    week: 'week',
+    month: 'month',
     legend: {
       newUsers: 'New users',
       returningUsers: 'Returning users',
@@ -74,11 +76,13 @@ export const adoptionInsightsMessages = {
   searches: {
     title: 'Top searches',
     totalCount: '{{count}} searches',
-    averagePrefix: 'An average of',
-    averageText: '{{count}} searches per {{period}}',
-    averageSuffix: 'were conducted during this period.',
+    averagePrefix: 'Average search count was',
+    averageText: '{{count}} per {{period}}',
+    averageSuffix: ' for this period.',
     hour: 'hour',
     day: 'day',
+    week: 'week',
+    month: 'month',
   },
   users: {
     title: 'Total number of users',
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/utils/__tests__/utils.test.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/utils/__tests__/utils.test.ts
@@ -29,6 +29,7 @@ import {
   formatDateWithRange,
   formatWeeklyBucket,
   formatTooltipHeaderLabel,
+  getGroupingLabel,
 } from '../utils';
 import { format, subDays } from 'date-fns';
 
@@ -363,3 +364,58 @@ describe('formatTooltipHeaderLabel', () => {
     expect(formatTooltipHeaderLabel('count')).toBe('Count');
   });
 });
+
+describe('getGroupingLabel', () => {
+  const mockTranslation = (key: string) => {
+    const translations: Record<string, string> = {
+      'activeUsers.hour': 'hour',
+      'activeUsers.day': 'day',
+      'activeUsers.week': 'week',
+      'activeUsers.month': 'month',
+      'searches.hour': 'hour',
+      'searches.day': 'day',
+      'searches.week': 'week',
+      'searches.month': 'month',
+    };
+    return translations[key] || key;
+  };
+
+  it('should return correct label for activeUsers section', () => {
+    expect(
+      getGroupingLabel('hourly', mockTranslation as any, 'activeUsers'),
+    ).toBe('hour');
+    expect(
+      getGroupingLabel('daily', mockTranslation as any, 'activeUsers'),
+    ).toBe('day');
+    expect(
+      getGroupingLabel('weekly', mockTranslation as any, 'activeUsers'),
+    ).toBe('week');
+    expect(
+      getGroupingLabel('monthly', mockTranslation as any, 'activeUsers'),
+    ).toBe('month');
+  });
+
+  it('should return correct label for searches section', () => {
+    expect(getGroupingLabel('hourly', mockTranslation as any, 'searches')).toBe(
+      'hour',
+    );
+    expect(getGroupingLabel('daily', mockTranslation as any, 'searches')).toBe(
+      'day',
+    );
+    expect(getGroupingLabel('weekly', mockTranslation as any, 'searches')).toBe(
+      'week',
+    );
+    expect(
+      getGroupingLabel('monthly', mockTranslation as any, 'searches'),
+    ).toBe('month');
+  });
+
+  it('should fallback to day for unknown grouping', () => {
+    expect(
+      getGroupingLabel('unknown', mockTranslation as any, 'activeUsers'),
+    ).toBe('day');
+    expect(
+      getGroupingLabel('unknown', mockTranslation as any, 'searches'),
+    ).toBe('day');
+  });
+});
diff --git a/workspaces/adoption-insights/plugins/adoption-insights/src/utils/utils.ts b/workspaces/adoption-insights/plugins/adoption-insights/src/utils/utils.ts
