@redocly/theme 0.67.0-next.4 → 0.67.0-next.5

package/src/core/hooks/use-page-actions.ts

@@ -22,14 +22,7 @@ import {
   removeTrailingSlash,
   withoutPathPrefix,
 } from '../utils/urls';
-
-function createPageActionResource(pageSlug: string, pageUrl: string) {
-  return {
-    id: pageSlug,
-    object: 'page' as const,
-    uri: pageUrl,
-  };
-}
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 const DEFAULT_ENABLED_ACTIONS = [
   'copy',
@@ -78,25 +71,22 @@ export function usePageActions(
 
         const isDocsMcp = !requiresMcpUrl;
 
-        const origin = IS_BROWSER ? window.location.origin : '';
-        const pageUrl = `${origin}${pageSlug}`;
-
         return createMCPAction({
           clientType,
           mcpConfig: config,
           translate,
           onClickCallback: isDocsMcp
             ? () =>
-                telemetry.sendPageActionsButtonClickedMessage([
+                telemetry.sendPageActionsClickedMessage([
                   {
-                    ...createPageActionResource(pageSlug, pageUrl),
-                    action_type: `docs-mcp-${clientType}` as const,
+                    ...getBaseDataAttributes('pageActions', 'button'),
+                    actionType: `docs-mcp-${clientType}` as const,
                   },
                 ])
             : undefined,
         });
       },
-    [mcpUrl, mcpConfig, translate, telemetry, pageSlug],
+    [mcpUrl, mcpConfig, translate, telemetry],
   );
 
   const result: PageAction[] = useMemo(() => {
@@ -113,7 +103,6 @@ export function usePageActions(
       ? window.location.origin
       : ((globalThis as { SSR_HOSTNAME?: string })['SSR_HOSTNAME'] ?? '');
     const pathname = addTrailingSlash(pageSlug);
-    const pageUrl = combineUrls(origin, pathname);
     const isRoot = withoutPathPrefix(pathname) === '/';
     const mdPageUrl = isRoot
       ? combineUrls(origin, pathname, 'index.html.md')
@@ -138,10 +127,10 @@ export function usePageActions(
             }
             const text = await result.text();
             ClipboardService.copyCustom(text);
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'copy',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'copy',
               },
             ]);
           } catch (error) {
@@ -157,10 +146,10 @@ export function usePageActions(
         iconComponent: MarkdownFullIcon,
         link: mdPageUrl,
         onClick: () => {
-          telemetry.sendPageActionsButtonClickedMessage([
+          telemetry.sendPageActionsClickedMessage([
             {
-              ...createPageActionResource(pageSlug, pageUrl),
-              action_type: 'view',
+              ...getBaseDataAttributes('pageActions', 'button'),
+              actionType: 'view',
             },
           ]);
         },
@@ -175,10 +164,10 @@ export function usePageActions(
           iconComponent: ChatGptIcon,
           link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'chatgpt',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'chatgpt',
               },
             ]);
             window.location.href = link;
@@ -195,10 +184,10 @@ export function usePageActions(
           iconComponent: ClaudeIcon,
           link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'claude',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'claude',
               },
             ]);
             window.location.href = link;

package/src/core/hooks/use-product-picker.ts

@@ -1,9 +1,10 @@
+import { useRef } from 'react';
 import { useNavigate } from 'react-router-dom';
 
 import { getProductClassName } from '@redocly/theme/components/Product/utils';
 
 import { useThemeHooks } from './use-theme-hooks';
-import { withPathPrefix } from '../utils';
+import { withPathPrefix, generateBeforeAfterContext } from '../utils';
 
 export function useProductPicker() {
   const { useCurrentProduct, useProducts, useTelemetry, useLoadAndNavigate } = useThemeHooks();
@@ -12,20 +13,33 @@ export function useProductPicker() {
   const telemetry = useTelemetry();
   const navigate = useNavigate();
   const loadAndNavigate = useLoadAndNavigate();
+  // An open dropdown can fire a menu item's onAction from an earlier render, so `product.link`
+  // may be stale (e.g. after a locale switch); resolve the live product via a ref.
+  const productsRef = useRef(products);
+  productsRef.current = products;
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
-    telemetry.sendProductPickedMessage([{ object: 'product', product: product.slug }]);
+    // match on `name` (locale-stable; link/slug are re-localized)
+    const freshProduct = productsRef.current.find((p) => p.name === product.name) ?? product;
+    telemetry.sendProductPickerChangedMessage([
+      ...generateBeforeAfterContext<'sendProductPickerChangedMessage'>(
+        'productPicker',
+        'dropdown',
+        { product: currentProduct?.slug || '' },
+        { product: freshProduct.slug },
+      ),
+    ]);
     if (typeof document === 'undefined') return;
 
-    if (product.name) {
+    if (freshProduct.name) {
       const root = document.documentElement;
       Array.from(root.classList)
         .filter((c) => c.startsWith('product-'))
         .forEach((c) => root.classList.remove(c));
-      root.classList.add(getProductClassName(product.name));
+      root.classList.add(getProductClassName(freshProduct.name));
     }
 
-    loadAndNavigate({ navigate, to: withPathPrefix(product.link) });
+    loadAndNavigate({ navigate, to: withPathPrefix(freshProduct.link) });
   }
   return {
     currentProduct,

package/src/core/hooks/use-telemetry-fallback.ts

@@ -1,50 +1,61 @@
-// eslint-disable-next-line no-warning-comments
-// TODO we need to create some common way to do this.
+// Fallback no-op telemetry used by `useThemeHooks` when no ThemeDataContext
+// provider supplies real hooks.
 export const useTelemetryFallback = () => ({
   send: () => {},
-  sendPageViewedMessage: () => {},
-  sendPageActionsButtonClickedMessage: () => {},
   sendErrorMessage: () => {},
   sendClientErrorMessage: () => {},
+  sendCatalogEntitiesFilterCheckboxToggledMessage: () => {},
+  sendCatalogEntitiesCopyDataSchemaClickedMessage: () => {},
+  sendCatalogEntitiesViewModeChangedMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchQueryMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage: () => {},
+  sendCatalogEntitiesListSearchQueryMessage: () => {},
+  sendCatalogEntitiesListSearchResultClickedMessage: () => {},
+  sendRedirectMessage: () => {},
+  sendCustomMessage: () => {},
+  sendSearchAIQueryMessage: () => {},
+  sendSearchAiOpenedMessage: () => {},
+  sendSearchAIFeedbackMessage: () => {},
+  sendLoginClickedMessage: () => {},
+  sendLoginProviderClickedMessage: () => {},
+  sendLogoutClickedMessage: () => {},
+  sendBannerViewedMessage: () => {},
+  sendBannerLinkClickedMessage: () => {},
+  sendBannerDismissedMessage: () => {},
   sendBreadcrumbClickedMessage: () => {},
-  sendColorModeSwitchedMessage: () => {},
-  sendSidebarItemClickedMessage: () => {},
-  sendSidebarItemExpandedMessage: () => {},
-  sendSidebarItemCollapsedMessage: () => {},
-  sendChangeLayoutButtonClickedMessage: () => {},
-  sendEditPageLinkClickedMessage: () => {},
-  sendCodeSnippetReportedMessage: () => {},
-  sendNavbarMenuItemClickedMessage: () => {},
-  sendLoginButtonClickedMessage: () => {},
-  sendLoginProviderButtonClickedMessage: () => {},
-  sendLogoutMenuItemClickedMessage: () => {},
-  sendLogoClickedMessage: () => {},
-  sendTocItemClickedMessage: () => {},
+  sendCatalogActionsClickedMessage: () => {},
   sendCatalogFilterChangedMessage: () => {},
   sendCatalogItemClickedMessage: () => {},
   sendScorecardLinkClickedMessage: () => {},
-  sendBackToCatalogButtonClickedMessage: () => {},
-  sendSidebarDrilldownBackButtonClickedMessage: () => {},
+  sendFilterCheckboxToggledMessage: () => {},
+  sendFeedbackMessage: () => {},
   sendFooterItemClickedMessage: () => {},
-  sendCatalogActionsButtonClickedMessage: () => {},
-  sendMobileMenuButtonCloseClickedMessage: () => {},
-  sendMobileMenuButtonOpenClickedMessage: () => {},
-  sendSearchInputResetButtonClickedMessage: () => {},
-  sendSearchRecentRemoveButtonClickedMessage: () => {},
+  sendNavbarMenuItemClickedMessage: () => {},
+  sendColorModeSwitchedMessage: () => {},
+  sendLanguagePickerChangedMessage: () => {},
+  sendProductPickerChangedMessage: () => {},
+  sendLogoClickedMessage: () => {},
+  sendCodeSnippetReportedMessage: () => {},
+  sendMobileMenuClosedMessage: () => {},
+  sendMobileMenuOpenedMessage: () => {},
+  sendPageViewedMessage: () => {},
+  sendPageTimeMessage: () => {},
+  sendPageActionsClickedMessage: () => {},
+  sendPageEditClickedMessage: () => {},
+  sendSidebarDrilldownBackClickedMessage: () => {},
+  sendSidebarItemClickedMessage: () => {},
+  sendSidebarExpandedMessage: () => {},
+  sendSidebarCollapsedMessage: () => {},
+  sendChangeLayoutClickedMessage: () => {},
+  sendRequestApiAccessClickedMessage: () => {},
+  sendVersionPickerChangedMessage: () => {},
+  sendSearchInputResetClickedMessage: () => {},
+  sendSearchResultClickedMessage: () => {},
+  sendSearchRecentRemoveClickedMessage: () => {},
   sendSearchRecentClickedMessage: () => {},
-  sendRequestApiAccessButtonClickedMessage: () => {},
-  sendVersionPickerSelectionChangeMessage: () => {},
-  sendProductPickedMessage: () => {},
-  sendFilterCheckboxToggledMessage: () => {},
-  sendLanguagePickerLocaleChangedMessage: () => {},
   sendSearchOpenedMessage: () => {},
   sendSearchQueryMessage: () => {},
-  sendSearchAiOpenedMessage: () => {},
-  sendSearchAIQueryMessage: () => {},
-  sendSearchAIFeedbackMessage: () => {},
-  sendFeedbackMessage: () => {},
-  sendSearchResultClickedMessage: () => {},
-  sendRedirectMessage: () => {},
+  sendTocItemClickedMessage: () => {},
   sendOpenapiDocsMessage: () => {},
   sendCopyCodeSnippetClickedMessage: () => {},
   sendViewedMessage: () => {},
@@ -67,10 +78,7 @@ export const useTelemetryFallback = () => ({
   sendAsyncapiDocsReferencedInClickedMessage: () => {},
   sendGraphqlDocsViewedMessage: () => {},
   sendGraphqlDocsPerformanceMetricsMessage: () => {},
+  sendGraphqlDocsDownloadDefinitionClickedMessage: () => {},
   sendGraphqlDocsReferencedInLinkClickedMessage: () => {},
   sendGraphqlDocsRequiredScopesModalOpenedMessage: () => {},
-  sendGraphqlDocsDownloadDefinitionClickedMessage: () => {},
-  sendBannerViewedMessage: () => {},
-  sendBannerLinkClickedMessage: () => {},
-  sendBannerDismissedMessage: () => {},
 });

package/src/core/utils/index.ts

@@ -46,3 +46,5 @@ export * from './content-segments';
 export * from './custom-catalog-options-casing';
 export * from './get-auto-dismiss-duration';
 export * from './tooltip-placement';
+export * from './telemetry/get-base-data-attributes';
+export * from './telemetry/generate-before-after-context';

package/src/core/utils/telemetry/generate-before-after-context.ts

@@ -0,0 +1,59 @@
+import type { AsyncApiRealmUI } from '@redocly/realm-asyncapi-sdk';
+
+import { getBaseDataAttributes } from './get-base-data-attributes';
+
+type UITelemetryClient = AsyncApiRealmUI.Telemetry;
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type UITelemetryClientMethods = {
+  [K in keyof UITelemetryClient]: UITelemetryClient[K] extends (...args: any) => any
+    ? UITelemetryClient[K]
+    : never;
+};
+type UITelemetryClientMethodKeys = {
+  [K in keyof UITelemetryClientMethods]: Parameters<
+    UITelemetryClientMethods[K]
+  >[0] extends readonly [any, any, ...any[]]
+    ? K
+    : never;
+}[keyof UITelemetryClientMethods];
+
+type EventSchemaProps<T extends UITelemetryClientMethodKeys> = Parameters<
+  UITelemetryClientMethods[T]
+>[0];
+
+type EventAfterContext<T extends UITelemetryClientMethodKeys> = EventSchemaProps<T>[0];
+type EventBeforeContext<T extends UITelemetryClientMethodKeys> = EventSchemaProps<T>[1];
+
+/**
+ * Builds a typed `[after, before]` tuple for Realm UI telemetry events whose AsyncAPI
+ * contract lists the updated state first, then the prior state (per CloudEvents styleguide).
+ *
+ * Each slice merges {@link getBaseDataAttributes} (`id`, `object`, `uri`) with the
+ * corresponding partial payload and sets `context` to `'after'` or `'before'`.
+ *
+ * @template T - Telemetry client method key whose `data` tuple is
+ *   `[after, before, ...]` (for example `'sendLanguagePickerChangedMessage'`).
+ * @param id - Stable resource identifier passed to {@link getBaseDataAttributes}
+ *   and included on both payloads.
+ * @param object - Resource kind passed to {@link getBaseDataAttributes}
+ *   and included on both payloads (for example `'dropdown'` or `'button'`).
+ * @param before - Event-specific fields for the prior state, excluding `id`, `object`,
+ *   `uri`, and `context` (filled by this helper).
+ * @param after - Event-specific fields for the updated state, excluding `id`, `object`,
+ *   `uri`, and `context` (filled by this helper).
+ * @returns A two-tuple in send order: the fully merged after payload, then the fully
+ *   merged before payload. Spread into the matching `send*Message` call.
+ */
+export function generateBeforeAfterContext<T extends UITelemetryClientMethodKeys>(
+  id: EventAfterContext<T>['id'],
+  object: EventAfterContext<T>['object'],
+  before: Omit<EventBeforeContext<T>, 'id' | 'object' | 'uri' | 'context'>,
+  after: Omit<EventAfterContext<T>, 'id' | 'object' | 'uri' | 'context'>,
+): [EventAfterContext<T> & { context: 'after' }, EventBeforeContext<T> & { context: 'before' }] {
+  const baseAttributes = getBaseDataAttributes(id, object);
+  return [
+    { ...baseAttributes, context: 'after' as const, ...after },
+    { ...baseAttributes, context: 'before' as const, ...before },
+  ];
+}

package/src/core/utils/telemetry/generate-resource-urn.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a resource URN for Realm UI telemetry.
+ * @param object - The object type.
+ * @param id - The resource ID.
+ * @returns The resource URN.
+ */
+export function generateResourceUrn<K, T, U>(object: K, id: T): U {
+  return `urn:redocly:realm:ui:${object}:${id}` as U;
+}

package/src/core/utils/telemetry/get-base-data-attributes.ts

@@ -0,0 +1,27 @@
+import { generateResourceUrn } from './generate-resource-urn';
+
+export type BaseDataAttributes<T, K, U> = {
+  /** Resource identifier (e.g. UI key, or page URL when tracking navigation). */
+  id: T;
+  /** Object kind used for telemetry categorization (e.g. `'button'`, `'page'`). */
+  object: K;
+  /** Resolved URI: the optional `url` when provided, otherwise a Realm UI resource URN. */
+  uri: U;
+};
+
+/**
+ * Builds the base fields for Realm UI telemetry payloads: `id`, `object`, and `uri`.
+ * When `url` is omitted, {@link generateResourceUrn} derives `uri` as
+ * `urn:redocly:realm:ui:{object}:{id}`.
+ */
+export function getBaseDataAttributes<T, K, U>(
+  id: T,
+  object: K,
+  url?: U,
+): BaseDataAttributes<T, K, U> {
+  return {
+    id,
+    object,
+    uri: url ?? generateResourceUrn(object, id),
+  };
+}