chore: add deprecation message in component pages (#10902)

Author: nnaydenow

packages/main/src/TableHeaderCellActionAI.ts

@@ -19,6 +19,7 @@ import "@ui5/webcomponents-icons/dist/ai.js";
  * @extends TableHeaderCellActionBase
  * @since 2.8.0
  * @public
+ * @experimental
  */
 @customElement({ tag: "ui5-table-header-cell-action-ai" })
 

packages/main/src/TableRowAction.ts

@@ -9,6 +9,7 @@ import TableRowActionBase from "./TableRowActionBase.js";
  * @extends TableRowActionBase
  * @since 2.7.0
  * @public
+ * @experimental
  */
 @customElement({ tag: "ui5-table-row-action" })
 

packages/main/src/TableRowActionNavigation.ts

@@ -19,6 +19,7 @@ import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
  * @extends TableRowActionBase
  * @since 2.7.0
  * @public
+ * @experimental
  */
 @customElement({ tag: "ui5-table-row-action-navigation" })
 

packages/main/src/types/TableCellHorizontalAlign.ts

@@ -2,6 +2,7 @@
  * Alignment of the <ui5-table-cell> component.
  *
  * @public
+ * @experimental
  */
 enum TableCellHorizontalAlign {
     /**

packages/main/src/types/TableGrowingMode.ts

@@ -2,6 +2,7 @@
  * Growing mode of the <ui5-table> component.
  *
  * @public
+ * @experimental
  */
 enum TableGrowingMode {
 	/**

packages/main/src/types/TableOverflowMode.ts

@@ -2,6 +2,7 @@
  * Column mode of the <ui5-table> component.
  *
  * @public
+ * @experimental
  */
 enum TableOverflowMode {
 	/**

packages/main/src/types/TableSelectionMode.ts

@@ -2,6 +2,7 @@
  * Selection modes of the <ui5-table> component.
  *
  * @public
+ * @experimental
  */
 enum TableSelectionMode {
 	/**

packages/tools/lib/cem/utils.mjs

@@ -241,7 +241,7 @@ const allowedTags = {
     eventParam: [...commonTags],
     method: [...commonTags, "param", "returns", "override"],
     class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
-    enum: [...commonTags],
+    enum: [...commonTags, "experimental",],
     enumMember: [...commonTags, "experimental",],
     interface: [...commonTags, "experimental",],
 };
@@ -264,17 +264,17 @@ const findDecorator = (node, decoratorName) => {
 
 const findAllDecorators = (node, decoratorName) => {
     if (typeof decoratorName === "string") {
-        return node?.decorators?.filter(decorator => decorator?.expression?.expression?.text === decoratorName ) || [];
+        return node?.decorators?.filter(decorator => decorator?.expression?.expression?.text === decoratorName) || [];
     }
 
     if (Array.isArray(decoratorName)) {
         return node?.decorators?.filter(decorator => {
-                if (decorator?.expression?.expression?.text) {
-                    return decoratorName.includes(decorator.expression.expression.text);
-                }
-
-                return false;
+            if (decorator?.expression?.expression?.text) {
+                return decoratorName.includes(decorator.expression.expression.text);
             }
+
+            return false;
+        }
         ) || [];
     }
 

packages/website/build-scripts/api-reference-generation/component-file.mjs

@@ -263,7 +263,11 @@ const parseDeclaration = (declaration, packageName) => {
 
     let sections = [];
 
-    if (declaration._ui5experimental) {
+    if (declaration.deprecated) {
+        sections.push(`:::warning
+${deprecatedText(declaration)}
+:::`)
+    } else if (declaration._ui5experimental) {
         sections.push(`:::info
 ${experimentalText(declaration)}
 :::`)
@@ -296,22 +300,29 @@ ${declaration._implementations.map(_implementation => `| ${_implementation.split
 
     let fileContent = sections.join("\n\n");
 
-    if (declaration._ui5experimental) {
+
+    if (declaration.deprecated) {
+        fileContent = addDeprecatedClassName(fileContent, declaration);
+    } else if (declaration._ui5experimental) {
         fileContent = addExperimentalClassName(fileContent, declaration);
     }
 
 
     return fileContent;
 }
 
-
-
 const experimentalText = declaration => {
-    return typeof declaration._ui5experimental === "boolean" ? 
+    return typeof declaration._ui5experimental === "boolean" ?
         "The following entity is available under an experimental flag and its API and behavior are subject to change."
         : declaration._ui5experimental;
 }
 
+const deprecatedText = declaration => {
+    return typeof declaration.deprecated === "boolean" ?
+        "The following entity is deprecated and will be removed in the next major version."
+        : declaration.deprecated;
+}
+
 
 const parseComponentDeclaration = (declaration, fileContent) => {
     if (!declaration || !fileContent) {
@@ -326,7 +337,15 @@ const parseComponentDeclaration = (declaration, fileContent) => {
         fileContent = enhanceFrontMatter(fileContent, "ui5_since", `${declaration._ui5since}`)
     }
 
-    if (declaration._ui5experimental) {
+    if (declaration.deprecated) {
+        fileContent = addDeprecatedClassName(fileContent, declaration);
+
+        fileContent = fileContent.replace("<%COMPONENT_OVERVIEW%>", `:::warning
+${deprecatedText(declaration)}
+:::
+
+${parseDeclarationDescription(declaration.description)}`)
+    } else if (declaration._ui5experimental) {
         fileContent = addExperimentalClassName(fileContent, declaration);
 
         fileContent = fileContent.replace("<%COMPONENT_OVERVIEW%>", `:::info
@@ -352,6 +371,25 @@ ${parseDeclarationDescription(declaration.description)}`)
 }
 
 const experimentalCssClass = "expComponentBadge";
+const deprecatedCssClass = "deprComponentBadge";
+
+const addDeprecatedClassName = (fileContent, declaration) => {
+    if (!declaration.deprecated) {
+        return fileContent;
+    }
+
+    const frontMatter = fileContent.match(/^---\n(?:.+\n)*---/);
+
+    if (!frontMatter) {
+        return `---
+sidebar_class_name: ${deprecatedCssClass}
+---
+
+${fileContent}`
+    }
+
+    return enhanceFrontMatter(fileContent, "sidebar_class_name", deprecatedCssClass)
+}
 
 const addExperimentalClassName = (fileContent, declaration) => {
     if (!declaration._ui5experimental) {
@@ -390,7 +428,7 @@ ${fileContent}`
     if (classLine && !hasExperimentalClass) {
         frontMatterLines[classLineIndex] = `${classLine} ${value}`;
     } else if (!classLine) {
-       frontMatterLines.splice(frontMatterLines.length - 1, 0, `${front_matter_name}: ${value}`);
+        frontMatterLines.splice(frontMatterLines.length - 1, 0, `${front_matter_name}: ${value}`);
     }
 
     return fileContent.replace(frontMatter[0], frontMatterLines.join("\n"));

packages/website/docs/_components_pages/ai/Button/Button.mdx

@@ -1,6 +1,6 @@
 ---
 slug: ../Button
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import ButtonMenu from "../../../_samples/ai/Button/ButtonMenu/ButtonMenu.md";

packages/website/docs/_components_pages/ai/Button/ButtonState.mdx

@@ -1,6 +1,6 @@
 ---
 slug: ../ButtonState
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 <%COMPONENT_OVERVIEW%>

packages/website/docs/_components_pages/ai/PromptInput.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Basic from "../../_samples/ai/PromptInput/Basic/Basic.md";

packages/website/docs/_components_pages/main/Table/Table.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../Table
-sidebar_class_name: expComponentBadge
 ---
 
 import Basic from "../../../_samples/main/Table/Basic/Basic.md";

packages/website/docs/_components_pages/main/Table/TableCell.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableCell
-sidebar_class_name: expComponentBadge
 ---
 
 import HAlign from "../../../_samples/main/Table/HAlign/HAlign.md";

packages/website/docs/_components_pages/main/Table/TableGrowing.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableGrowing
-sidebar_class_name: expComponentBadge
 ---
 
 import Growing from "../../../_samples/main/Table/Growing/Growing.md";

packages/website/docs/_components_pages/main/Table/TableHeaderCell.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableHeaderCell
-sidebar_class_name: expComponentBadge
 ---
 
 import Popin from "../../../_samples/main/Table/Popin/Popin.md";

packages/website/docs/_components_pages/main/Table/TableHeaderCellActionAI.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableHeaderCellActionAI
-sidebar_class_name: expComponentBadge
 ---
 
 import HeaderCellActionAI from "../../../_samples/main/Table/HeaderCellActionAI/HeaderCellActionAI.md";

packages/website/docs/_components_pages/main/Table/TableHeaderRow.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableHeaderRow
-sidebar_class_name: expComponentBadge
 ---
 
 import StickyHeader from "../../../_samples/main/Table/StickyHeader/StickyHeader.md";

packages/website/docs/_components_pages/main/Table/TableRow.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableRow
-sidebar_class_name: expComponentBadge
 ---
 
 import Interactive from "../../../_samples/main/Table/Interactive/Interactive.md";

packages/website/docs/_components_pages/main/Table/TableRowAction.mdx

@@ -1,6 +1,6 @@
 ---
 slug: ../../TableRowAction
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import RowAction from "../../../_samples/main/Table/RowAction/RowAction.md";

packages/website/docs/_components_pages/main/Table/TableRowActionNavigation.mdx

@@ -1,6 +1,6 @@
 ---
 slug: ../../TableRowActionNavigation
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import RowActionNavigation from "../../../_samples/main/Table/RowActionNavigation/RowActionNavigation.md";

packages/website/docs/_components_pages/main/Table/TableSelection.mdx

@@ -1,6 +1,5 @@
 ---
 slug: ../../TableSelection
-sidebar_class_name: expComponentBadge
 ---
 
 import Selection from "../../../_samples/main/Table/Selection/Selection.md";

packages/website/docs/_components_pages/main/Table/TableVirtualizer.mdx

@@ -1,6 +1,6 @@
 ---
 slug: ../../TableVirtualizer
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Virtualizer from "../../../_samples/main/Table/Virtualizer/Virtualizer.md";

packages/website/docs/components/patterns/AI Acknowledgement.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Basic from "../../_samples/patterns/AIAcknowledgement/Basic/Basic.md";

packages/website/docs/components/patterns/AI CustomPrompt/AI CustomPrompt.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 :::info

packages/website/docs/components/patterns/AI GuidedPrompt.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Popover from "../../_samples/patterns/AIGuidedPrompt/Popover/Popover.md";

packages/website/docs/components/patterns/AI QuickPrompt.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Basic from "../../_samples/patterns/AIQuickPrompt/Basic.md";

packages/website/docs/components/patterns/AI Regenerate.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Basic from "../../_samples/patterns/AIRegenerate/Basic/Basic.md";

packages/website/docs/components/patterns/SelectionAssistant/Selection Assistant.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_class_name: newComponentBadge expComponentBadge
+sidebar_class_name: newComponentBadge
 ---
 
 import Input from "../../../components/patterns/SelectionAssistant/InputSelectionAssistant/Basic/Basic.md";

packages/website/src/css/custom.css

@@ -209,7 +209,8 @@ code {
 }
 
 .newComponentBadge,
-.expComponentBadge {
+.expComponentBadge,
+.deprComponentBadge {
   position: relative;
 }
 
@@ -227,7 +228,27 @@ code {
   pointer-events: none;
 }
 
-.newComponentBadge.expComponentBadge:before {
+.deprComponentBadge:before {
+  color: #fff;
+  position: absolute;
+  top: 0.25rem;
+  inset-inline-end: 1rem;
+  border-radius: 0.5rem;
+  padding: 0.125rem 0.25rem;
+  box-sizing: border-box;
+  font-size: 0.75rem;
+  content: "depr";
+  background: #ffb700e0;
+  pointer-events: none;
+}
+
+.deprComponentBadge.expComponentBadge:before {
+	display: none;
+}
+
+
+.newComponentBadge.expComponentBadge:before,
+.newComponentBadge.deprComponentBadge:before {
   inset-inline-end: 3.25rem;
 }
 
@@ -246,11 +267,13 @@ code {
 }
 
 .theme-doc-sidebar-item-category.newComponentBadge:after,
-.theme-doc-sidebar-item-category.expComponentBadge:before {
+.theme-doc-sidebar-item-category.expComponentBadge:before,
+.theme-doc-sidebar-item-category.deprComponentBadge:before {
     inset-inline-end: 2.25rem;
 }
 
-.theme-doc-sidebar-item-category.newComponentBadge.expComponentBadge:before {
+.theme-doc-sidebar-item-category.newComponentBadge.expComponentBadge:before,
+.theme-doc-sidebar-item-category.newComponentBadge.deprComponentBadge:before {
     inset-inline-end: 4.5rem;
 }