feature: support classNames props

Author: v.voloshin

src/assets/h-drag.svg

@@ -13,7 +13,7 @@ import * as LazyLoadingStories from './lazy-loading-scrollable.stories';
 
 <Meta title="Docs" />
 
-<Title of={SimpleStories} />
+<Title>Docs</Title>
 
 <Description of={SimpleStories} />
 

src/assets/v-drag.svg

@@ -15,13 +15,21 @@ import Scrollbar from './scrollbar';
 import cx from './utils/classnames';
 import generateUniqId from './utils/generateUniqId';
 import composeRef from './utils/composeRef';
+import makeClassName from './utils/makeClassName';
 import useHorizontalScrollbarHandlers from './hooks/useHorizontalScrollbarHandlers';
 import useVerticalScrollbarHandlers from './hooks/useVerticalScrollbarHandlers';
 import useResizeObserver from './hooks/useResizeObserver';
 import useScrollHandlers from './hooks/useScrollHandlers';
 import usePointerHandlers from './hooks/usePointerHandlers';
+import type { ClassNamesType } from './types';
 import './scrollable.css';
 
+export type {
+  ClassNamesType,
+  ClassNameStringOrFnType,
+  ClassNameStringOrFnReturnType,
+} from './types';
+
 export type ScrollablePropsType = HTMLAttributes<HTMLElement> & {
   /**
    * show thumbs on mouse hover, effects only for pointing devices like a mouse
@@ -59,6 +67,19 @@ export type ScrollablePropsType = HTMLAttributes<HTMLElement> & {
    * * `[className]__scrollbar__thumb` - thumb element class
    */
   className?: string;
+  /**
+   * <a name="classnames-props-anchor"></a>
+   * A set of classes for styling the scrollbar area. The values for the classes can be a string or a function that takes the appropriate argument and returns a string.
+   *
+   * Supported classes:
+   *
+   * * `scrollable` - the wrapper element class containing the scrollable area and scrollbars, implemented as a dynamic grid.
+   * * `area` - scrollable element class - uses CSS overflow property
+   * * `content` - content element class
+   * * `scrollbar` - scrollbar element class
+   * * `thumb` - thumb element class
+   */
+  classNames?: Partial<ClassNamesType>;
   /**
    * Applies styles to the overflow-enabled scrollable element.
    * The width and height properties are applied exclusively to the inner content element, excluding scrollbars.
@@ -105,6 +126,7 @@ function Scrollable({
   children,
   showThumbOnHover = false,
   className = undefined,
+  classNames = undefined,
   style = undefined,
   wrapperStyle = undefined,
   onLeftEdgeReached = undefined,
@@ -166,20 +188,30 @@ function Scrollable({
     ignoresScrollEvents,
   });
 
+
   return (
     <CssVariables>
       <div
-        className={cx('scrollable', {
-          'scrollable_has-horizontal-scrollbar': hasHorizontalScrollbar,
-          'scrollable_has-vertical-scrollbar': hasVerticalScrollbar,
-          'scrollable_show-mouse-on-hover': showThumbOnHover,
-        }, className)}
+        className={cx(
+          'scrollable',
+          {
+            'scrollable_has-horizontal-scrollbar': hasHorizontalScrollbar,
+            'scrollable_has-vertical-scrollbar': hasVerticalScrollbar,
+            'scrollable_show-mouse-on-hover': showThumbOnHover,
+          },
+          makeClassName(classNames?.scrollable, {
+            hasHorizontalScrollbar,
+            hasVerticalScrollbar,
+            showThumbOnHover,
+          }),
+          className
+        )}
         style={wrapperStyle}
       >
         <div
           {...props}
           id={scrollableId}
-          className={cx('scrollable__area', {
+          className={cx('scrollable__area', makeClassName(classNames?.area), {
             [`${className}__area`]: !!className,
           })}
           style={style}
@@ -188,7 +220,7 @@ function Scrollable({
           {...scrollHandlers}
         >
           <div
-            className={cx('scrollable__content', {
+            className={cx('scrollable__content', makeClassName(classNames?.content), {
               [`${className}__content`]: !!className,
             })}
             {...pointerHandlers}
@@ -201,12 +233,14 @@ function Scrollable({
           isVertical
           aria-controls={scrollableId}
           className={className}
+          classNames={classNames}
           {...verticalScrollbarHandlers}
         />
         <Scrollbar
           ref={hScrollbarRef}
           aria-controls={scrollableId}
           className={className}
+          classNames={classNames}
           {...horizontalScrollbarHandlers}
         />
         <div data-testid="extreme-point" />

src/scrollable.mdx

@@ -5,16 +5,6 @@
   background: var(--scrollbar-background, none);
   border: var(--scrollbar-border, none);
 
-  &_vertical &__thumb {
-    height: 0;
-    width: var(--thumb-size, 6px);
-  }
-
-  &_horizontal &__thumb {
-    height: var(--thumb-size, 6px);
-    width: 0;
-  }
-
   &__track {
     box-sizing: border-box;
     width: 100%;
@@ -29,4 +19,14 @@
     cursor: pointer;
     touch-action: none;
   }
+
+  &__thumb_vertical {
+    height: 0;
+    width: var(--thumb-size, 6px);
+  }
+
+  &__thumb_horizontal {
+    height: var(--thumb-size, 6px);
+    width: 0;
+  }
 }

src/scrollable.tsx

@@ -6,15 +6,19 @@ import {
   memo,
 } from 'react';
 import cx from './utils/classnames';
+import makeClassName from './utils/makeClassName';
+import type { ClassNamesType } from './types';
 import './scrollbar.css';
 
 type ScrollbarPropsType = HTMLAttributes<HTMLElement> & {
   isVertical?: boolean;
+  classNames?: Partial<Pick<ClassNamesType, 'scrollbar' | 'thumb'>>
 };
 
 function Scrollbar({
   isVertical = false,
   className,
+  classNames,
   ...props
 }: ScrollbarPropsType, ref: Ref<HTMLDivElement>): ReactElement {
   const ariaLabel = isVertical
@@ -26,20 +30,31 @@ function Scrollbar({
     : 'horizontal';
 
   return (
-    <div className={cx('scrollable__scrollbar', {
-      'scrollable__scrollbar_horizontal': !isVertical,
-      'scrollable__scrollbar_vertical': isVertical,
-      [`${className}__scrollbar`]: !!className,
-    })}>
+    <div className={cx(
+      'scrollable__scrollbar',
+      {
+        'scrollable__scrollbar_horizontal': !isVertical,
+        'scrollable__scrollbar_vertical': isVertical,
+        [`${className}__scrollbar`]: !!className,
+      },
+      makeClassName(classNames?.scrollbar, { isVertical }),
+    )}
+    >
       <div className={cx('scrollable__scrollbar__track', {
         [`${className}__scrollbar__track`]: !!className,
       })}>
         <div
           {...props}
           ref={ref}
-          className={cx('scrollable__scrollbar__thumb', {
-            [`${className}__scrollbar__thumb`]: !!className,
-          })}
+          className={cx(
+            'scrollable__scrollbar__thumb',
+            {
+              'scrollable__scrollbar__thumb_horizontal': !isVertical,
+              'scrollable__scrollbar__thumb_vertical': isVertical,
+              [`${className}__scrollbar__thumb`]: !!className,
+            },
+            makeClassName(classNames?.thumb, { isVertical }),
+          )}
           role="scrollbar"
           aria-orientation={ariaOrientation}
           aria-label={ariaLabel}

src/scrollbar.css

@@ -18,6 +18,49 @@ const meta = {
       options: [false, true],
       control: { type: 'radio' },
     },
+    className: { table: { category: 'customization' } },
+    style: { table: { category: 'customization' } },
+    wrapperStyle: { table: { category: 'customization' } },
+    classNames: {
+      table: {
+        category: 'customization',
+        type: {
+          summary: 'Partial<ClassNamesType>',
+          detail: `
+type ClassNameStringOrFnType<Payload = undefined> =
+  string
+  | (Payload extends undefined ? () => string : (payload: Payload) => string);
+
+type ClassNamesType = {
+  /**
+   * the wrapper element class containing the scrollable area and scrollbars, implemented as a dynamic grid.
+   */
+  scrollable: ClassNameStringOrFnType;
+  /**
+   * scrollable element class - uses CSS overflow property
+   */
+  area: ClassNameStringOrFnType;
+  /**
+   * content element class
+   */
+  content: ClassNameStringOrFnType;
+  /**
+   * scrollbar element class
+   */
+  scrollbar: ClassNameStringOrFnType<{
+    isVertical: boolean;
+  }>;
+  /**
+   * thumb element class
+   */
+  thumb: ClassNameStringOrFnType<{
+    isVertical: boolean;
+  }>;
+}
+          `,
+        },
+      },
+    },
   },
   parameters: {
     controls: {