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

package/src/components/Search/SearchDialog.tsx

@@ -7,7 +7,7 @@ import type { SearchFacetCount, SearchItemData } from '@redocly/theme/core/types
 import { SearchInput } from '@redocly/theme/components/Search/SearchInput';
 import { SearchShortcut } from '@redocly/theme/components/Search/SearchShortcut';
 import { Button } from '@redocly/theme/components/Button/Button';
-import { breakpoints, concatClassNames } from '@redocly/theme/core/utils';
+import { breakpoints, concatClassNames, getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { Portal } from '@redocly/theme/components/Portal/Portal';
 import { SearchItem } from '@redocly/theme/components/Search/SearchItem';
 import { SearchRecent } from '@redocly/theme/components/Search/SearchRecent';
@@ -172,9 +172,8 @@ export function SearchDialog({
             addSearchHistoryItem(query);
             telemetry.sendSearchResultClickedMessage([
               {
-                object: 'search',
+                ...getBaseDataAttributes('searchResultItem', 'search', item.document.url),
                 query: query,
-                url: item.document.url,
                 totalResults: results.length.toString(),
                 index: index.toString(),
                 searchEngine: mode,
@@ -259,9 +258,7 @@ export function SearchDialog({
                           }
                           telemetry.sendSearchAiOpenedMessage([
                             {
-                              id: 'searchAiButton',
-                              object: 'search',
-                              uri: 'urn:redocly:realm:ui:search:searchAiButton',
+                              ...getBaseDataAttributes('searchAiButton', 'search'),
                               method: 'ai_search_button',
                             },
                           ]);
@@ -355,9 +352,7 @@ export function SearchDialog({
                         }
                         telemetry.sendSearchAiOpenedMessage([
                           {
-                            id: 'searchAiInput',
-                            object: 'search',
-                            uri: 'urn:redocly:realm:ui:search:searchAiInput',
+                            ...getBaseDataAttributes('searchAiInput', 'search'),
                             method: 'ai_search_input',
                           },
                         ]);
@@ -370,9 +365,7 @@ export function SearchDialog({
                           }
                           telemetry.sendSearchAiOpenedMessage([
                             {
-                              id: 'searchAiInput',
-                              object: 'search',
-                              uri: 'urn:redocly:realm:ui:search:searchAiInput',
+                              ...getBaseDataAttributes('searchAiInput', 'search'),
                               method: 'ai_search_input',
                             },
                           ]);
@@ -474,7 +467,7 @@ export function SearchDialog({
                         onSelect={(query, index) => {
                           telemetry.sendSearchRecentClickedMessage([
                             {
-                              object: 'search',
+                              ...getBaseDataAttributes('searchRecentItem', 'search'),
                               query,
                               index: index.toString(),
                               searchSessionId,

package/src/components/Search/SearchInput.tsx

@@ -9,6 +9,7 @@ import { Button } from '@redocly/theme/components/Button/Button';
 import { useInputKeyCommands, useRecentSearches, useThemeHooks } from '@redocly/theme/core/hooks';
 import { CloseFilledIcon } from '@redocly/theme/icons/CloseFilledIcon/CloseFilledIcon';
 import { ChevronLeftIcon } from '@redocly/theme/icons/ChevronLeftIcon/ChevronLeftIcon';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export type SearchInputProps = {
   placeholder?: string;
@@ -51,7 +52,9 @@ export function SearchInput({
   const handleOnReset = () => {
     onChange('');
     addSearchHistoryItem(value);
-    telemetry.sendSearchInputResetButtonClickedMessage();
+    telemetry.sendSearchInputResetClickedMessage([
+      getBaseDataAttributes('searchInputReset', 'search'),
+    ]);
   };
 
   return (

package/src/components/Search/SearchRecent.tsx

@@ -3,7 +3,7 @@ import styled from 'styled-components';
 
 import type { JSX } from 'react';
 
-import { breakpoints } from '@redocly/theme/core/utils';
+import { breakpoints, getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { useThemeHooks, useRecentSearches } from '@redocly/theme/core/hooks';
 import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
 import { RecentlyViewedIcon } from '@redocly/theme/icons/RecentlyViewedIcon/RecentlyViewedIcon';
@@ -25,7 +25,9 @@ export function SearchRecent({ onSelect, className }: SearchRecentProps): JSX.El
   const handleOnRemove = (e: React.MouseEvent<SVGSVGElement, MouseEvent>, item: string) => {
     e.stopPropagation();
     removeSearchHistoryItem(item);
-    telemetry.sendSearchRecentRemoveButtonClickedMessage();
+    telemetry.sendSearchRecentRemoveClickedMessage([
+      getBaseDataAttributes('searchRecentRemove', 'search'),
+    ]);
   };
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>, item: string, index: number) => {

package/src/components/SidebarActions/SidebarActions.tsx

@@ -11,6 +11,7 @@ import {
   ControlsWrapChangeLayoutButtons,
 } from '@redocly/theme/components/SidebarActions/styled';
 import { Tooltip } from '@redocly/theme/components/Tooltip/Tooltip';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export { LayoutVariant };
 
@@ -57,9 +58,13 @@ export const SidebarActions = ({
             onClick={() => {
               onChangeCollapseSidebarClick();
               if (collapsedSidebar) {
-                telemetry.sendSidebarItemExpandedMessage();
+                telemetry.sendSidebarExpandedMessage([
+                  getBaseDataAttributes('sidebarExpand', 'button'),
+                ]);
               } else {
-                telemetry.sendSidebarItemCollapsedMessage();
+                telemetry.sendSidebarCollapsedMessage([
+                  getBaseDataAttributes('sidebarCollapse', 'button'),
+                ]);
               }
             }}
             size="small"
@@ -76,7 +81,9 @@ export const SidebarActions = ({
             layout={layout}
             onClick={() => {
               onChangeViewClick();
-              telemetry.sendChangeLayoutButtonClickedMessage();
+              telemetry.sendChangeLayoutClickedMessage([
+                getBaseDataAttributes('changeLayout', 'button'),
+              ]);
             }}
           />
         </ControlsWrapChangeLayoutButtons>

package/src/components/TableOfContent/TableOfContent.tsx

@@ -10,7 +10,12 @@ import {
   useThemeConfig,
   useFullHeight,
 } from '@redocly/theme/core/hooks';
-import { breakpoints, getDisplayedHeadings, getLeastDepth } from '@redocly/theme/core/utils';
+import {
+  breakpoints,
+  getDisplayedHeadings,
+  getLeastDepth,
+  getBaseDataAttributes,
+} from '@redocly/theme/core/utils';
 
 export type TableOfContentProps = {
   headings?: Array<MdHeading | null> | null | undefined;
@@ -62,7 +67,7 @@ export function TableOfContent(props: TableOfContentProps): JSX.Element | null {
               data-testid={`toc-${heading.value}`}
               onClick={(e) => {
                 e.preventDefault();
-                telemetry.sendTocItemClickedMessage();
+                telemetry.sendTocItemClickedMessage([getBaseDataAttributes('tocItem', 'toc')]);
                 handleHeadingClick(heading.id);
               }}
             />

package/src/components/UserMenu/LoginButton.tsx

@@ -4,6 +4,7 @@ import type { ButtonVariant, ButtonSize } from '@redocly/theme/components/Button
 
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { Button } from '@redocly/theme/components/Button/Button';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export type LoginButtonProps = {
   href: string;
@@ -36,7 +37,9 @@ export function LoginButton({
         data-translation-key={label ? undefined : labelTranslationKey}
         to={href}
         languageInsensitive
-        onClick={() => telemetry.sendLoginButtonClickedMessage()}
+        onClick={() =>
+          telemetry.sendLoginClickedMessage([getBaseDataAttributes('login', 'button')])
+        }
         data-testid="login-btn"
         extraClass={className}
         variant={variant}

package/src/components/UserMenu/LogoutMenuItem.tsx

@@ -5,6 +5,7 @@ import type { JSX } from 'react';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { LogoutIcon } from '@redocly/theme/icons/LogoutIcon/LogoutIcon';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export type LogoutMenuItemProps = {
   iconOnly?: boolean;
@@ -18,7 +19,7 @@ export function LogoutMenuItem({ iconOnly, className }: LogoutMenuItemProps): JS
   const { translate } = useTranslate();
 
   const handleClick = () => {
-    telemetry.sendLogoutMenuItemClickedMessage();
+    telemetry.sendLogoutClickedMessage([getBaseDataAttributes('logoutItem', 'userMenu')]);
     handleLogout();
   };
 

package/src/core/hooks/search/use-search-dialog.ts

@@ -5,6 +5,7 @@ import hotkeys from 'hotkeys-js';
 import { useThemeHooks } from '../use-theme-hooks';
 import { useThemeConfig } from '../use-theme-config';
 import { useSearchSession } from '../../contexts';
+import { getBaseDataAttributes } from '../../utils';
 
 export function useSearchDialog() {
   const [isOpen, setIsOpen] = useState(false);
@@ -20,7 +21,12 @@ export function useSearchDialog() {
     if (hotKeys) {
       hotkeys(hotKeys, (ev) => {
         setIsOpen(true);
-        telemetry.sendSearchOpenedMessage([{ object: 'search', method: 'shortcut' }]);
+        telemetry.sendSearchOpenedMessage([
+          {
+            ...getBaseDataAttributes('searchDialogId', 'search'),
+            method: 'shortcut',
+          },
+        ]);
         ev.preventDefault();
       });
 
@@ -30,7 +36,12 @@ export function useSearchDialog() {
   }, [hotKeys]);
 
   const onOpen = useCallback(function () {
-    telemetry.sendSearchOpenedMessage([{ object: 'search', method: 'click' }]);
+    telemetry.sendSearchOpenedMessage([
+      {
+        ...getBaseDataAttributes('searchDialogId', 'search'),
+        method: 'click',
+      },
+    ]);
     setIsOpen(true);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);

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

@@ -3,6 +3,7 @@ import { useMemo } from 'react';
 import type { DisplayBanner } from '@redocly/theme/components/Banner/Banner';
 
 import { useThemeHooks } from './use-theme-hooks';
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 const noop = (): void => {};
 const noopLink = (_href: string): void => {};
@@ -28,11 +29,11 @@ export function useBannerTelemetry(
       };
     }
 
-    const bannerUri = 'urn:redocly:realm:ui:banner:banner-id';
     const payload = {
-      id: 'banner-id' as const,
-      object: 'banner' as const,
-      uri: bannerUri,
+      ...getBaseDataAttributes<'bannerId', 'banner', 'urn:redocly:realm:ui:banner:bannerId'>(
+        'bannerId',
+        'banner',
+      ),
       trackingId: displayBanner.trackingId,
       hash: displayBanner.hash,
       color: displayBanner.color,

package/src/core/hooks/use-color-switcher.ts

@@ -6,6 +6,7 @@ import { useThemeConfig } from './use-theme-config';
 import { useThemeHooks } from './use-theme-hooks';
 import { createStore, useStore } from './use-store';
 import { DEFAULT_COLOR_MODES } from '../constants';
+import { generateBeforeAfterContext } from '../utils';
 
 const COLOR_MODE_KEY = 'colorSchema';
 const colorModeStore = createStore<string>({
@@ -51,7 +52,12 @@ export const useColorSwitcher = () => {
       root.classList.remove('notransition');
     });
     telemetry.sendColorModeSwitchedMessage([
-      { object: 'color_mode', from: activeColorMode, to: newMode },
+      ...generateBeforeAfterContext<'sendColorModeSwitchedMessage'>(
+        'colorMode',
+        'button',
+        { mode: activeColorMode },
+        { mode: newMode },
+      ),
     ]);
     setActiveColorMode(newMode);
   };

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/types/search.ts

@@ -132,4 +132,5 @@ export enum ToolCallName {
   GetEndpointInfo = 'get-endpoint-info',
   GetSecuritySchemes = 'get-security-schemes',
   GetFullApiDescription = 'get-full-api-description',
+  Execute = 'execute',
 }

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),
+  };
+}