feat(ThemeProvider): apply Fiori scrollbar styling to all scroll containers (#5978)

MarcusNotheis · Lukas742 · web-flow · commit 9a611fde3b3c · 2024-07-01T12:35:32.000+02:00
BREAKING CHANGE: the `GlobalStyleClasses` enum has been removed

---------

Co-authored-by: Lukas Harbarth &lt;lukas.harbarth@sap.com&gt;
diff --git a/docs/MigrationGuide.mdx b/docs/MigrationGuide.mdx
@@ -38,6 +38,15 @@ function MyRootComponent() {
 }
 ```
 
+### Scrollbar Styling
+
+Starting with v2, the `ThemeProvider` will apply the Fiori styles to all scrollbars on the page.
+If you have previously used our global style classes `sapScrollBar` or `inheritingSapScrollBar`, you can now remove them.
+
+To opt-out of this behavior, you can add the `.ui5-content-native-scrollbars` class to the element to prevent the scrollbar styling from being applied.
+
+More details can be found in our [Styling Knowledge Base](?path=/docs/knowledge-base-styling--docs#scrollbars).
+
 ## Removed hooks
 
 ### `useResponsiveContentPadding`
diff --git a/docs/knowledge-base/Styling.mdx b/docs/knowledge-base/Styling.mdx
@@ -37,26 +37,20 @@ You can change CSS Variables on any level - in the head, or on every single elem
 A full list of all supported CSS Variables can be found [here](https://github.com/SAP/ui5-webcomponents-react/blob/main/packages/base/src/styling/ThemingParameters.ts)
 or in the [theming-base-content](https://github.com/SAP/theming-base-content/tree/master/content/Base/baseLib) repo.
 
-## Reuse global style classes
+## Scrollbars
 
-The `ThemeProvider` component is offering global css classes that can be reused in your applications code to help you to achieve a Fiori look-and-feel.
-All globally available style classes are tracked in the `GlobalStyleClasses` enum which can be imported from `import { GlobalStyleClasses } from "@ui5/webcomponents-react";`.
-
-| CSS Class                | Description                                                                                                                      |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `sapScrollBar`           | If added to an container that supports scrolling, the scrollbar will be styled according to Fiori guidelines.                    |
-| `inheritingSapScrollBar` | If added to a container, the scollbars of the container and of all of its children will be styled according to Fiori guidelines. |
+Rendering our `ThemeProvider` will apply the Fiori styles to all scrollbars on the page.
+If you want to opt-out of this behavior, you can add the `.ui5-content-native-scrollbars` class to the respective element to prevent the scrollbar styling from being applied.
 
 <MessageStrip
+  design={MessageStripDesign.Information}
   hideCloseButton
-  style={{ marginBlockEnd: '1rem' }}
-  children="With our next major release (v2.0.0), both style classes will be removed as then the SAP scrollbar will be used per
-  default for the whole application."
+  children="Due to the limited configuration options for scrollbars, you must apply this class to each scroll-container element individually."
 />
 
-### Use default browser scrollbar
-
-Some components like the `ObjectPage`, `DynamicPage` and `AnalyticalTable` use the CSS class `sapScrollBar` by default. To prevent components from using the custom scrollbar, you can pass `data-native-scrollbar` as prop.
+```tsx
+<ObjectPage className="ui5-content-native-scrollbars">{children}</ObjectPage>
+```
 
 ## Style your own components
 
diff --git a/packages/main/src/components/AnalyticalTable/index.tsx b/packages/main/src/components/AnalyticalTable/index.tsx
@@ -31,8 +31,7 @@ import {
   AnalyticalTableSelectionBehavior,
   AnalyticalTableSelectionMode,
   AnalyticalTableSubComponentsBehavior,
-  AnalyticalTableVisibleRowCountMode,
-  GlobalStyleClasses
+  AnalyticalTableVisibleRowCountMode
 } from '../../enums/index.js';
 import {
   COLLAPSE_NODE,
@@ -655,9 +654,9 @@ const AnalyticalTable = forwardRef<AnalyticalTableDomRef, AnalyticalTablePropTyp
 
   const tableClasses = clsx(
     classNames.table,
-    GlobalStyleClasses.sapScrollBar,
     withNavigationHighlight && classNames.hasNavigationIndicator,
-    showVerticalEndBorder && classNames.showVerticalEndBorder
+    showVerticalEndBorder && classNames.showVerticalEndBorder,
+    className?.includes('ui5-content-native-scrollbars') && 'ui5-content-native-scrollbars'
   );
 
   const handleOnLoadMore = (e) => {
@@ -746,7 +745,6 @@ const AnalyticalTable = forwardRef<AnalyticalTableDomRef, AnalyticalTablePropTyp
             data-per-page={internalVisibleRowCount}
             data-component-name="AnalyticalTableContainer"
             ref={tableRef}
-            data-native-scrollbar={props['data-native-scrollbar']}
             className={tableClasses}
           >
             <div className={classNames.tableHeaderBackgroundElement} />
@@ -837,9 +835,9 @@ const AnalyticalTable = forwardRef<AnalyticalTableDomRef, AnalyticalTablePropTyp
               tableRef={tableRef}
               handleVerticalScrollBarScroll={handleVerticalScrollBarScroll}
               ref={verticalScrollBarRef}
-              data-native-scrollbar={props['data-native-scrollbar']}
               scrollContainerRef={scrollContainerRef}
               parentRef={parentRef}
+              nativeScrollbar={className?.includes('ui5-content-native-scrollbars')}
             />
           )}
         </FlexBox>
diff --git a/packages/main/src/components/AnalyticalTable/scrollbars/VerticalScrollbar.tsx b/packages/main/src/components/AnalyticalTable/scrollbars/VerticalScrollbar.tsx
@@ -2,7 +2,7 @@ import { ThemingParameters, useStylesheet, useSyncRef } from '@ui5/webcomponents
 import { clsx } from 'clsx';
 import type { MutableRefObject, RefObject } from 'react';
 import { forwardRef, useEffect, useRef } from 'react';
-import { FlexBoxDirection, GlobalStyleClasses } from '../../../enums/index.js';
+import { FlexBoxDirection } from '../../../enums/index.js';
 import { FlexBox } from '../../FlexBox/index.js';
 import { classNames, styleData } from './VerticalScrollbar.module.css.js';
 
@@ -11,14 +11,21 @@ interface VerticalScrollbarProps {
   tableRef: RefObject<any>;
   handleVerticalScrollBarScroll: any;
   tableBodyHeight: number;
-  'data-native-scrollbar'?: any;
   scrollContainerRef: MutableRefObject<HTMLDivElement>;
   parentRef: MutableRefObject<HTMLDivElement>;
+  nativeScrollbar: boolean;
 }
 
 export const VerticalScrollbar = forwardRef<HTMLDivElement, VerticalScrollbarProps>((props, ref) => {
-  const { internalRowHeight, tableRef, handleVerticalScrollBarScroll, tableBodyHeight, scrollContainerRef, parentRef } =
-    props;
+  const {
+    internalRowHeight,
+    tableRef,
+    handleVerticalScrollBarScroll,
+    tableBodyHeight,
+    scrollContainerRef,
+    nativeScrollbar,
+    parentRef
+  } = props;
   const [componentRef, containerRef] = useSyncRef(ref);
   const scrollElementRef = useRef(null);
   useStylesheet(styleData, VerticalScrollbar.displayName);
@@ -58,8 +65,7 @@ export const VerticalScrollbar = forwardRef<HTMLDivElement, VerticalScrollbarPro
           height: tableRef.current ? `${tableBodyHeight}px` : '0'
         }}
         onScroll={handleVerticalScrollBarScroll}
-        data-native-scrollbar={props['data-native-scrollbar']}
-        className={`${GlobalStyleClasses.sapScrollBar} ${classNames.scrollbar}`}
+        className={clsx(classNames.scrollbar, nativeScrollbar && 'ui5-content-native-scrollbars')}
         data-component-name="AnalyticalTableVerticalScrollbar"
       >
         <div
diff --git a/packages/main/src/components/MessageView/index.tsx b/packages/main/src/components/MessageView/index.tsx
@@ -10,7 +10,7 @@ import { useI18nBundle, useStylesheet, useSyncRef } from '@ui5/webcomponents-rea
 import { clsx } from 'clsx';
 import type { ReactElement, ReactNode } from 'react';
 import { Children, forwardRef, Fragment, isValidElement, useCallback, useEffect, useState } from 'react';
-import { FlexBoxDirection, GlobalStyleClasses } from '../../enums/index.js';
+import { FlexBoxDirection } from '../../enums/index.js';
 import { ALL, LIST_NO_DATA } from '../../i18n/i18n-defaults.js';
 import { MessageViewContext } from '../../internal/MessageViewContext.js';
 import type { CommonProps } from '../../types/index.js';
@@ -145,12 +145,7 @@ const MessageView = forwardRef<MessageViewDomRef, MessageViewPropTypes>((props,
     setListFilter(e.detail.selectedItems.at(0).dataset.key as never);
   };
 
-  const outerClasses = clsx(
-    classNames.container,
-    GlobalStyleClasses.sapScrollBar,
-    className,
-    selectedMessage && classNames.showDetails
-  );
+  const outerClasses = clsx(classNames.container, className, selectedMessage && classNames.showDetails);
 
   return (
     <div ref={componentRef} {...rest} className={outerClasses}>
diff --git a/packages/main/src/components/ObjectPage/index.tsx b/packages/main/src/components/ObjectPage/index.tsx
@@ -13,7 +13,7 @@ import {
 import { clsx } from 'clsx';
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 import { cloneElement, forwardRef, isValidElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { GlobalStyleClasses, ObjectPageMode } from '../../enums/index.js';
+import { ObjectPageMode } from '../../enums/index.js';
 import { addCustomCSSWithScoping } from '../../internal/addCustomCSSWithScoping.js';
 import { safeGetChildrenArray } from '../../internal/safeGetChildrenArray.js';
 import { useObserveHeights } from '../../internal/useObserveHeights.js';
@@ -549,7 +549,6 @@ const ObjectPage = forwardRef<HTMLDivElement, ObjectPagePropTypes>((props, ref)
 
   const objectPageClasses = clsx(
     classNames.objectPage,
-    GlobalStyleClasses.sapScrollBar,
     className,
     mode === ObjectPageMode.IconTabBar && classNames.iconTabBarMode
   );
diff --git a/packages/main/src/components/ThemeProvider/ThemeProvider.css b/packages/main/src/components/ThemeProvider/ThemeProvider.css
@@ -14,7 +14,7 @@
 @import '../../themes/sap_horizon_hcb.css';
 @import '../../themes/sap_horizon_hcw.css';
 
-.inheritingSapScrollBar *:not([data-native-scrollbar]) {
+:not(.ui5-content-native-scrollbars) {
   &::-webkit-scrollbar {
     background-color: var(--sapScrollBar_TrackColor);
     -webkit-border-start: var(--_ui5wcr_Scrollbar_Border);
@@ -49,41 +49,3 @@
     width: var(--sapScrollBar_Dimension);
   }
 }
-
-.sapScrollBar:not([data-native-scrollbar]) {
-  &::-webkit-scrollbar {
-    background-color: var(--sapScrollBar_TrackColor);
-    -webkit-border-start: var(--_ui5wcr_Scrollbar_Border);
-  }
-
-  &::-webkit-scrollbar-thumb {
-    border-radius: var(--_ui5wcr_Scrollbar_BorderRadius);
-    background-color: var(--sapScrollBar_FaceColor);
-  }
-
-  &::-webkit-scrollbar-corner {
-    background-color: var(--sapScrollBar_TrackColor);
-  }
-
-  &::-webkit-scrollbar-thumb {
-    &:hover {
-      background-color: var(--sapScrollBar_Hover_FaceColor);
-    }
-
-    &:horizontal {
-      height: var(--sapScrollBar_Dimension);
-    }
-
-    &:vertical {
-      width: var(--sapScrollBar_Dimension);
-    }
-  }
-
-  &::-webkit-scrollbar:horizontal {
-    height: var(--sapScrollBar_Dimension);
-  }
-
-  &::-webkit-scrollbar:vertical {
-    width: var(--sapScrollBar_Dimension);
-  }
-}
diff --git a/packages/main/src/enums/GlobalStyleClasses.ts b/packages/main/src/enums/GlobalStyleClasses.ts
diff --git a/packages/main/src/enums/index.ts b/packages/main/src/enums/index.ts
@@ -13,7 +13,6 @@ export * from './FlexBoxAlignItems.js';
 export * from './FlexBoxDirection.js';
 export * from './FlexBoxJustifyContent.js';
 export * from './FlexBoxWrap.js';
-export * from './GlobalStyleClasses.js';
 export * from './GridPosition.js';
 export * from './IndicationColor.js';
 export * from './LoaderType.js';
