docs: add badges (#7689)

Author: Lukas742

.storybook/components/Badge.tsx

@@ -0,0 +1,35 @@
+import '@ui5/webcomponents/dist/Tag.js';
+import type Tag from '@ui5/webcomponents/dist/Tag.js';
+// with sb 9.1.2 the explicit React import is required for components used in manager.tsx - not sure if this is a bug
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import React from 'react';
+
+declare global {
+  interface JSX {
+    IntrinsicElements: {
+      'ui5-tag': Tag;
+    };
+  }
+}
+
+const TAGS = {
+  deprecated: { design: 'Set1', colorScheme: '3', title: 'Deprecated', label: 'Depr' },
+  custom: { design: 'Set2', colorScheme: '6', title: 'No / Limited Design', label: 'Custom' },
+  experimental: { design: 'Set1', colorScheme: '8', title: 'Experimental', label: 'Exp' },
+};
+
+function Badge({ type }: { type: 'deprecated' | 'custom' | 'experimental' }) {
+  return (
+    <ui5-tag
+      design={TAGS[type].design}
+      color-scheme={TAGS[type].colorScheme}
+      class="side-nav-badge"
+      title={TAGS[type].title}
+    >
+      {TAGS[type].label}
+    </ui5-tag>
+  );
+}
+
+Badge.displayName = 'Badge';
+export { Badge };

.storybook/components/DocsHeader.tsx

@@ -1,3 +1,4 @@
+import { Badge } from '@sb/components/Badge';
 import type { Controls } from '@storybook/addon-docs/blocks';
 import { Description, Subtitle, Title, useOf } from '@storybook/addon-docs/blocks';
 import ButtonDesign from '@ui5/webcomponents/dist/types/ButtonDesign.js';
@@ -45,14 +46,25 @@ interface InfoTableProps {
   isChart?: boolean;
   experimental?: boolean;
   of: ComponentProps<typeof Controls>['of'];
+  deprecationText?: string;
 }
 
-export const InfoTable = ({ of, since, subComponents, mergeSubComponents }: InfoTableProps) => {
+export const InfoTable = ({
+  of,
+  since,
+  subComponents,
+  mergeSubComponents,
+  deprecationText,
+  isChart,
+}: InfoTableProps) => {
   const context = useOf<'meta'>(of);
   const { csfFile, preparedMeta } = context;
+  const { tags } = preparedMeta;
   const moduleName = csfFile.meta.component.displayName;
+  const isDeprecated = tags.includes('deprecated');
+  const isCustom = tags.includes('custom') || isChart;
 
-  const wcSubComponents = useGetSubComponentsOfModule(moduleName.replace('V2', ''), preparedMeta.tags);
+  const wcSubComponents = useGetSubComponentsOfModule(moduleName.replace('V2', ''), tags);
   const subComps = mergeSubComponents
     ? [...(subComponents ?? []), ...(wcSubComponents ?? [])]
     : (subComponents ?? wcSubComponents);
@@ -68,6 +80,7 @@ export const InfoTable = ({ of, since, subComponents, mergeSubComponents }: Info
       await navigator.clipboard.write([data]);
     }
   };
+
   return (
     <table className={classes.infoTable}>
       <tbody>
@@ -99,6 +112,30 @@ export const InfoTable = ({ of, since, subComponents, mergeSubComponents }: Info
             </td>
           </tr>
         )}
+        {isDeprecated && (
+          <tr>
+            <th>
+              <Label>Deprecated</Label>
+            </th>
+            <td>
+              <Text>{deprecationText}</Text>
+            </td>
+          </tr>
+        )}
+        {isCustom && (
+          <tr>
+            <th>
+              <Label>Custom Component</Label>
+            </th>
+            <td>
+              <Text>
+                {isChart
+                  ? 'Charts are custom-built without defined design specifications! They use the Fiori color palette, but functionality and especially accessibility may not meet standard app requirements.'
+                  : 'This component either only partially follows design specifications or lacks them entirely. Please refer to the component description for details.'}
+              </Text>
+            </td>
+          </tr>
+        )}
         {!!subComps.length && (
           <tr className={classes.hoverTr}>
             <th>
@@ -124,17 +161,39 @@ export const InfoTable = ({ of, since, subComponents, mergeSubComponents }: Info
   );
 };
 
-export const DocsHeader = ({ of, since, subComponents, mergeSubComponents, isChart, experimental }: InfoTableProps) => {
+export const DocsHeader = ({
+  of,
+  since,
+  subComponents,
+  mergeSubComponents,
+  isChart,
+  experimental,
+  deprecationText,
+}: InfoTableProps) => {
+  const context = useOf<'meta'>(of);
+  const { preparedMeta } = context;
+  const { tags } = preparedMeta;
+  const isDeprecated = tags.includes('deprecated');
+  const isCustom = tags.includes('custom') || isChart;
   return (
     <ThemeProvider>
       <FlexBox alignItems={FlexBoxAlignItems.Center} className={classes.titleRow}>
         <Title />
-        {experimental && <Label className={classes.experimentalLabel}>experimental</Label>}
+        {!isDeprecated && experimental && <Badge type="experimental" />}
+        {!isDeprecated && isCustom && <Badge type="custom" />}
+        {isDeprecated && <Badge type="deprecated" />}
         <span style={{ flexGrow: 1 }} />
         <Links isChart={isChart} />
       </FlexBox>
       <Subtitle />
-      <InfoTable of={of} since={since} subComponents={subComponents} mergeSubComponents={mergeSubComponents} />
+      <InfoTable
+        of={of}
+        since={since}
+        subComponents={subComponents}
+        mergeSubComponents={mergeSubComponents}
+        deprecationText={deprecationText}
+        isChart={isChart}
+      />
       <TableOfContent />
       <Description />
       {isChart && (

.storybook/manager-head.html

@@ -21,16 +21,28 @@
     background-color: transparent !important;
   }
 
-  /*experimental components */
-  #ai-promptinput::after,
-  #ai-button::after,
-  #inputs-tokenizer::after,
-  #inputs-search::after,
-  #modals-popovers-usermenu::after,
-  #modals-popovers-usersettingsdialog::after,
-  #charts-timelinechart::after {
-    content: '(experimental)';
-    overflow: hidden;
+  /* hide tags from tags-popover */
+  #list-item-tag-experimental,
+  #list-item-tag-deprecated,
+  #list-item-tag-custom,
+  #list-item-tag-cem-module\:Dialog,
+  #list-item-tag-cem-module\:ResponsivePopover,
+  #list-item-tag-excludeFromSidebar,
+  #list-item-tag-extends\:\@ui5\/webcomponents {
+    display: none;
+  }
+
+  /* side-nav badge styles */
+  .sidebar-item > button,
+  .sidebar-item > a {
+    align-items: center;
+    flex-wrap: wrap;
+  }
+  .side-nav-badge {
+    font-size: var(--sapFontSmallSize);
+  }
+  .side-nav-badge::part(root) {
+    padding-block: 0;
   }
 </style>
 

.storybook/manager.js .storybook/manager.tsx.storybook/manager.js renamed to .storybook/manager.tsx

@@ -1,5 +1,11 @@
+// with sb 9.1.2 the explicit React import is required - not sure if this is a bug
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import React from 'react';
 import { addons } from 'storybook/manager-api';
-import { Fiori4ReactTheme } from './theme';
+import { Badge } from './components/Badge.js';
+import { Fiori4ReactTheme } from './theme.js';
+
+const customTags = new Set(['package:@ui5/webcomponents-react-charts', 'custom']);
 
 addons.setConfig({
   theme: Fiori4ReactTheme,
@@ -12,12 +18,12 @@ addons.setConfig({
    * display left panel that shows a list of stories
    * @type {number}
    */
-  navSize: 240,
+  navSize: 280,
   /**
    * display floating search box to search through stories
    * @type {Boolean}
    */
-  showSearchBox: false,
+  showSearchBox: true,
   /**
    * The size of the addon panel when in the bottom position
    * @type {number}
@@ -52,6 +58,33 @@ addons.setConfig({
         return !item.tags.includes('excludeFromSidebar');
       },
     },
+    renderLabel: (item) => {
+      const tags = item.tags ?? [];
+      const isCustom = tags.some((tag) => customTags.has(tag));
+      const isExperimental = tags.includes('experimental');
+      const isDeprecated = tags.includes('deprecated');
+
+      if (item.type !== 'component' && item.type !== 'docs') {
+        return item.name;
+      }
+
+      if (isDeprecated) {
+        return (
+          <>
+            {item.name}
+            <Badge type="deprecated" />
+          </>
+        );
+      }
+
+      return (
+        <>
+          {item.name}
+          {isCustom && <Badge type="custom" />}
+          {isExperimental && <Badge type="experimental" />}
+        </>
+      );
+    },
   },
   toolbar: {
     'storybook/viewport': { hidden: true },

.storybook/preview-head.html

@@ -165,6 +165,17 @@
   }
   /*UserSettingsDialog story - end*/
 
+  /* Badge styles */
+  .side-nav-badge {
+    font-size: var(--sapFontSmallSize);
+    margin-inline-start: 0.25rem;
+    padding-block-end: 0.3rem;
+    align-self: flex-end;
+  }
+  .side-nav-badge::part(root) {
+    padding-block: 0;
+  }
+
   /* TODO remove this workaround as soon as https://github.com/storybookjs/storybook/issues/20497 is fixed */
   .docs-story > div > div[scale] {
     min-height: 20px;

.storybook/utils.ts

@@ -22,8 +22,12 @@ export const MAPPED_THEMES = [
 export const excludePropsForAbstract = ['className', 'style'];
 
 export function useGetCem(storyTags: string[]) {
+  const extendsAnnotation = storyTags?.find((tag) => tag.startsWith('extends:'));
   const packageAnnotation = storyTags?.find((tag) => tag.startsWith('package:'));
-  switch (packageAnnotation) {
+  const annotation = extendsAnnotation ?? packageAnnotation;
+
+  switch (annotation) {
+    case 'extends:@ui5/webcomponents':
     case 'package:@ui5/webcomponents':
       return cemMain;
     case 'package:@ui5/webcomponents-fiori':

packages/ai/src/components/Button/Button.stories.tsx

@@ -19,7 +19,7 @@ const meta = {
   args: {
     design: ButtonDesign.Default,
   },
-  tags: ['package:@ui5/webcomponents-ai'],
+  tags: ['package:@ui5/webcomponents-ai', 'experimental'],
 } satisfies Meta<typeof Button>;
 
 export default meta;

packages/ai/src/components/PromptInput/PromptInput.stories.tsx

@@ -12,7 +12,7 @@ const meta = {
   args: {
     valueState: ValueState.None,
   },
-  tags: ['package:@ui5/webcomponents-ai'],
+  tags: ['package:@ui5/webcomponents-ai', 'experimental'],
 } satisfies Meta<typeof PromptInput>;
 
 export default meta;

packages/charts/src/components/BarChart/BarChart.stories.tsx

@@ -12,6 +12,7 @@ import { BarChart } from './BarChart.js';
 const meta = {
   title: 'BarChart',
   component: BarChart,
+  tags: ['package:@ui5/webcomponents-react-charts'],
   argTypes: {
     dataset: {
       control: { disable: true },

packages/charts/src/components/BarChart/BarChart.tsx

@@ -126,6 +126,8 @@ export interface BarChartProps extends IChartBaseProps {
 
 /**
  * A `BarChart` is a data visualization where each category is represented by a rectangle, with the width of the rectangle being proportional to the values being plotted.
+ *
+ * __Note:__ Charts are custom-built __without__ defined design specifications! They use the Fiori color palette, but functionality and especially accessibility may not meet standard app requirements.
  */
 const BarChart = forwardRef<HTMLDivElement, BarChartProps>((props, ref) => {
   const {