docs(cypress-commands): show deprecation notice in docs (#7396)

Author: Lukas742

.storybook/components/CommandsAndQueries.tsx

@@ -1,4 +1,5 @@
 import { Heading, Markdown } from '@storybook/blocks';
+import { Tag as WCRTag } from '@ui5/webcomponents-react';
 import dedent from 'dedent';
 import { Fragment } from 'react';
 
@@ -116,6 +117,7 @@ interface FunctionMetadata {
   members: Members;
   path: Path[];
   namespace: string;
+  deprecated: Record<string, any>;
 }
 
 function generateMdCodeBlock(codeStr: string) {
@@ -196,13 +198,37 @@ function generateDescription(description: RootNode) {
   }, '');
 }
 
+function formatHtmlFromNode(node: any): string {
+  if (!node) return '';
+
+  switch (node.type) {
+    case 'root':
+      return node.children.map(formatHtmlFromNode).join('');
+    case 'paragraph':
+      return `<p>${node.children.map(formatHtmlFromNode).join('')}</p>`;
+    case 'text':
+      return node.value;
+    case 'inlineCode':
+      return `<code>${node.value}</code>`;
+    default:
+      return '';
+  }
+}
+
 export const CommandsAndQueries = ({ api }: { api: FunctionMetadata[] }) => {
   return api
     .sort((a, b) => a.name.localeCompare(b.name))
     .map((item) => {
       return (
         <Fragment key={item.name}>
-          <Heading>{item.name}</Heading>
+          <Heading>
+            {item.name}
+            {!!item.deprecated && (
+              <WCRTag style={{ marginInlineStart: '1rem' }} design="Critical">
+                deprecated
+              </WCRTag>
+            )}
+          </Heading>
           <code>
             {item.name}(
             {item.params
@@ -215,6 +241,12 @@ export const CommandsAndQueries = ({ api }: { api: FunctionMetadata[] }) => {
               return generateGenericType(type);
             })}
           </code>
+          {!!item.deprecated && (
+            <>
+              <br />
+              {<b dangerouslySetInnerHTML={{ __html: formatHtmlFromNode(item.deprecated) }} />}
+            </>
+          )}
           <Markdown>{generateDescription(item.description)}</Markdown>
           {generateExample(item.tags)}
           {!!item.params.length && (

packages/cypress-commands/src/commands.ts

@@ -84,6 +84,7 @@ declare global {
        * @param text text of the ui5-option that should be clicked
        * @param options ClickOptions
        *
+       * @deprecated This command is deprecated. Please use `clickDropdownMenuItemByText` instead.
        *
        * @example cy.get('[ui5-select]').clickUi5SelectOptionByText('Option2');
        */
@@ -94,7 +95,7 @@ declare global {
        *
        * __Note:__ The select popover must be visible, otherwise it can lead to unwanted side effects.
        *
-       * @deprecated: This command is deprecated. Please use `clickDropdownMenuItem` instead.
+       * @deprecated This command is deprecated. Please use `clickDropdownMenuItem` instead.
        *
        * @example cy.get('[ui5-option]').clickUi5SelectOption();
        */
@@ -208,6 +209,14 @@ Cypress.Commands.add('clickUi5ListItemByText', { prevSubject: 'optional' }, (sub
 });
 
 Cypress.Commands.add('clickUi5SelectOptionByText', { prevSubject: 'element' }, (subject, text, options = {}) => {
+  Cypress.log({
+    name: 'Deprecation',
+    message: ['`clickUi5SelectOptionByText` is deprecated! Please use `clickDropdownMenuItemByText` instead.'],
+    consoleProps: () => ({
+      deprecated: 'clickUi5SelectOptionByText',
+      replacement: 'clickDropdownMenuItemByText',
+    }),
+  });
   cy.wrap(subject)
     .contains(text)
     .then(($option) => {
@@ -217,6 +226,14 @@ Cypress.Commands.add('clickUi5SelectOptionByText', { prevSubject: 'element' }, (
 });
 
 Cypress.Commands.add('clickUi5SelectOption', { prevSubject: 'element' }, (subject, options = {}) => {
+  Cypress.log({
+    name: 'Deprecation',
+    message: ['`clickUi5SelectOption` is deprecated! Please use `clickDropdownMenuItem` instead.'],
+    consoleProps: () => ({
+      deprecated: 'clickUi5SelectOption',
+      replacement: 'clickDropdownMenuItem',
+    }),
+  });
   cy.wrap(subject).then(($option) => {
     // @ts-expect-error: cannot set $option to use OptionDomRef
     const domRef = $option.get(0).getDomRef();