From 88493dd2a0c2e929d6151cd307d4514caa555224 Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Mon, 14 Apr 2025 13:37:47 +0200 Subject: [PATCH] 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 --- docs/src/css/custom.css | 30 ++++++++++++++++++++++++- docs/src/theme/DocCardList/index.js | 13 +++++++++++ docs/src/theme/DocSidebarItems/index.js | 14 ++++++++++++ docs/src/utils/deprecated-items.js | 29 ++++++++++++++++++++++++ 4 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 docs/src/theme/DocCardList/index.js create mode 100644 docs/src/theme/DocSidebarItems/index.js create mode 100644 docs/src/utils/deprecated-items.js diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 5083c842e9..50035f2541 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -612,4 +612,32 @@ p strong { position: absolute; top: 0; left: 0; -} \ No newline at end of file +} + +/* + 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; +} diff --git a/docs/src/theme/DocCardList/index.js b/docs/src/theme/DocCardList/index.js new file mode 100644 index 0000000000..c9c24e2b8f --- /dev/null +++ b/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 ( + <> + + + ); +} diff --git a/docs/src/theme/DocSidebarItems/index.js b/docs/src/theme/DocSidebarItems/index.js new file mode 100644 index 0000000000..35ad429fa2 --- /dev/null +++ b/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 ( + <> + + + ); +} diff --git a/docs/src/utils/deprecated-items.js b/docs/src/utils/deprecated-items.js new file mode 100644 index 0000000000..353a619d30 --- /dev/null +++ b/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 = {label} + return { + zitadelLifecycleDeprecated: zitadelLifecycleDeprecated, + ...itemRest, + className, + label: wrappedLabel, + }; + }); + const sortedItems = [...withDeprecated].sort((a, b) => { + return a.zitadelLifecycleDeprecated - b.zitadelLifecycleDeprecated; + }); + return { + ...rest, + items: sortedItems, + }; +}