docs: strikethrough deprecated APIs (#9740)

# Which Problems Are Solved

The docs overview pages and navs don't visually distinguish between
deprecated and GA APIs.
This makes it hard to find the right methods for the job already.
As we are implementing the resource API and continously deprecate
obsolete APIs, this only gets worse.

# How the Problems Are Solved

The UI items in docs overview pages are striked through and pushed to
the bottom of the list.
This applies to side navs as well as card lists.

For example, [see management user
methods](https://docs-git-strikethrough-deprecated-apis-zitadel.vercel.app/docs/apis/resources/mgmt/users):

![image](https://github.com/user-attachments/assets/a12ccd92-3a70-4854-8ebf-b771ff151083)

A method is considered deprecated if it has this option set in the
protos rpc definition:

```protobuf
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
    deprecated: true;
}
```

# Additional Changes

None

# Additional Context

- Relates to #9680

---------

Co-authored-by: David Skewis <david@zitadel.com>

docs/src/css/custom.css

@@ -612,4 +612,32 @@ p strong {
   position: absolute;
   top: 0;
   left: 0;
-}
+}
+
+/*
+  The overview list components are enriched by swizzled DocCardList and DocSidebarItems wrappers.
+  Deprecated list item titles have the class zitadel-lifecycle-deprecated.
+  We strike them through, because this is well-known practice and reduces mental overhead for finding the right method to solve a task.
+ */
+.card:has(.zitadel-lifecycle-deprecated) {
+  position: relative;
+}
+
+.card:has(.zitadel-lifecycle-deprecated)::after {
+  content: "DEPRECATED";
+  position: absolute;
+  top: 10px;
+  right: 10px;
+  background-color: var(--ifm-color-danger-contrast-background);
+  color: var(--ifm-color-danger-contrast-foreground);
+  font-size: 12px;
+  font-weight: 600;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.zitadel-lifecycle-deprecated {
+  text-decoration: line-through;
+}

docs/src/theme/DocCardList/index.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import DocCardList from '@theme-original/DocCardList';
+import toCustomDeprecatedItemsProps from "../../utils/deprecated-items";
+
+// The DocCardList component is used in generated index pages for API services.
+// We customize it for deprecated items.
+export default function DocCardListWrapper(props) {
+    return (
+        <>
+            <DocCardList {...toCustomDeprecatedItemsProps(props)} />
+        </>
+    );
+}

docs/src/theme/DocSidebarItems/index.js

@@ -0,0 +1,14 @@
+import React from 'react';
+import DocSidebarItems from '@theme-original/DocSidebarItems';
+import toCustomDeprecatedItemsProps from '../../utils/deprecated-items.js';
+
+// The DocSidebarItems component is used in generated side navs for API services.
+// We wrap the original to push deprecated items to the bottom and give them a CSS class.
+// This lets us easily style them differently in docs/src/css/custom.css.
+export default function DocSidebarItemsWrapper(props) {
+    return (
+        <>
+            <DocSidebarItems {...toCustomDeprecatedItemsProps(props)} />
+        </>
+    );
+}

docs/src/utils/deprecated-items.js

@@ -0,0 +1,29 @@
+import React from "react";
+
+// This function changes a ListComponents input properties.
+// Deprecated items are pushed to the bottom of the list and its labels are given the CSS class zitadel-lifecycle-deprecated.
+// They are styled in docs/src/css/custom.css.
+export default function (props) {
+    const { items = [], ...rest } = props;
+    if (!Array.isArray(items)) {
+        // Do nothing if items is not an array
+        return props;
+    }
+    const withDeprecated = [...items].map(({className, label, ...itemRest}) => {
+        const zitadelLifecycleDeprecated = className?.indexOf('menu__list-item--deprecated') > -1
+        const wrappedLabel = <span className={zitadelLifecycleDeprecated ? "zitadel-lifecycle-deprecated" : undefined}>{label}</span>
+        return {
+            zitadelLifecycleDeprecated: zitadelLifecycleDeprecated,
+            ...itemRest,
+            className,
+            label: wrappedLabel,
+        };
+    });
+    const sortedItems = [...withDeprecated].sort((a, b) => {
+        return a.zitadelLifecycleDeprecated - b.zitadelLifecycleDeprecated;
+    });
+    return {
+        ...rest,
+        items: sortedItems,
+    };
+}