@cdx-ui/components 0.2.2 → 0.2.4

package/src/components/ScopedTheme/index.tsx

@@ -1,7 +1,12 @@
 import type { ComponentProps } from 'react';
 import { ScopedTheme as UniwindScopedTheme } from 'uniwind';
 
-export type ScopedThemeProps = ComponentProps<typeof UniwindScopedTheme>;
+export type ScopedThemeProps = ComponentProps<typeof UniwindScopedTheme> & {
+  /** The theme forced on the subtree, such as `'dark'` or `'light'`. */
+  theme: ComponentProps<typeof UniwindScopedTheme>['theme'];
+  /** The subtree that renders in `theme`. */
+  children?: ComponentProps<typeof UniwindScopedTheme>['children'];
+};
 
 /**
  * Forces a specific theme on a component subtree, regardless of the application's

package/src/components/ScrollShadow/gradient.ts

@@ -0,0 +1,48 @@
+import { I18nManager } from 'react-native';
+import { SCROLL_SHADOW_SURFACE_FROM_CLASS, type ScrollShadowSurface } from './styles';
+
+type ScrollShadowEdge = 'start' | 'end';
+type ScrollShadowOrientation = 'horizontal' | 'vertical';
+
+export function getWebSurfaceGradientClasses(
+  surface: ScrollShadowSurface,
+  orientation: ScrollShadowOrientation,
+  edge: ScrollShadowEdge,
+): string {
+  const fromClass = SCROLL_SHADOW_SURFACE_FROM_CLASS[surface];
+
+  if (orientation === 'vertical') {
+    return edge === 'start'
+      ? `bg-gradient-to-b ${fromClass} to-transparent`
+      : `bg-gradient-to-t ${fromClass} to-transparent`;
+  }
+
+  // ltr:/rtl: so the fade flips with layout direction on the first paint,
+  // not after a later scroll re-render.
+  return edge === 'start'
+    ? `ltr:bg-gradient-to-r rtl:bg-gradient-to-l ${fromClass} to-transparent`
+    : `ltr:bg-gradient-to-l rtl:bg-gradient-to-r ${fromClass} to-transparent`;
+}
+
+export function getInlineBackgroundImage(
+  color: string,
+  orientation: ScrollShadowOrientation,
+  edge: ScrollShadowEdge,
+  isRTL = I18nManager.isRTL,
+): string {
+  if (orientation === 'vertical') {
+    return edge === 'start'
+      ? `linear-gradient(to bottom, ${color}, transparent)`
+      : `linear-gradient(to top, ${color}, transparent)`;
+  }
+
+  if (isRTL) {
+    return edge === 'start'
+      ? `linear-gradient(to left, ${color}, transparent)`
+      : `linear-gradient(to right, ${color}, transparent)`;
+  }
+
+  return edge === 'start'
+    ? `linear-gradient(to right, ${color}, transparent)`
+    : `linear-gradient(to left, ${color}, transparent)`;
+}

package/src/components/ScrollShadow/index.tsx

@@ -1,119 +1,350 @@
-import { Children, cloneElement, isValidElement, type ReactNode } from 'react';
-import { StyleSheet, View, type ViewStyle } from 'react-native';
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useRef,
+  type ReactElement,
+} from 'react';
+import { Animated, Platform, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import { useCSSVariable, useResolveClassNames } from 'uniwind';
+import { dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
 import { cn } from '@cdx-ui/utils';
+import { getInlineBackgroundImage, getWebSurfaceGradientClasses } from './gradient';
 import {
+  SCROLL_SHADOW_SIZE_PX,
+  SCROLL_SHADOW_SURFACE_CSS_VARS,
   scrollShadowContainerVariants,
-  scrollShadowOverlayVariants,
+  scrollShadowEdgeVariants,
   scrollShadowVariants,
+  type ScrollShadowSize,
+  type ScrollShadowSurface,
   type ScrollShadowVariantProps,
 } from './styles';
-import { useScrollShadow, type ScrollShadowCapability } from './useScrollShadow';
+import {
+  composeScrollHandler,
+  isReanimatedScrollHandler,
+  useReanimatedComposedScrollHandler,
+} from './useComposedScrollHandler';
+import {
+  useScrollShadowTracker,
+  type ScrollShadowCapability,
+  type ScrollShadowDistance,
+  type UseScrollShadowReturn,
+} from './useScrollShadow';
+
+export type {
+  ScrollShadowCapability,
+  UseScrollShadowOptions,
+  UseScrollShadowReturn,
+} from './useScrollShadow';
+export { useScrollShadow } from './useScrollShadow';
 
-export type { ScrollShadowCapability };
+export type ScrollShadowVisibility = 'auto' | 'both' | 'start' | 'end' | 'none';
 
 export interface ScrollShadowProps extends ScrollShadowVariantProps {
-  children: ReactNode;
+  /**
+   * The scroll view to decorate: a `ScrollView`, `FlatList`, or `VirtualizedList`, passed as
+   * the direct child. With a forced `visibility`, any single view works.
+   */
+  children: ReactElement;
+  /** Classes for the wrapping view, for example `h-full` or `flex-1` to bound the scroller. */
   className?: string;
+  /** Style for the wrapping view. */
+  style?: StyleProp<ViewStyle>;
   /**
-   * Tailwind `from-*` utility for edge overlays — match the surface behind the scroll area.
-   * Pair with a low opacity (e.g. `from-surface-secondary/40`) for a light fade.
-   * @default 'from-background/35'
+   * Scroll axis that gets fades.
+   * @default inferred from the child's `horizontal` prop, otherwise `'vertical'`
    */
-  fadeFromClassName?: string;
+  orientation?: 'horizontal' | 'vertical';
   /**
-   * Shadow fade size in pixels.
-   * @default 64
+   * Theme surface the fade blends into. Match it to the background behind the scroller.
+   * @default 'background'
    */
-  size?: number;
+  surface?: ScrollShadowSurface;
   /**
-   * Scroll offset before showing edge shadows.
+   * Fade depth along the scroll axis: `small` is 32px, `default` is 40px, `large` is 72px.
+   * @default 'default'
+   */
+  size?: ScrollShadowSize;
+  /**
+   * Which edges show a fade. `auto` follows the scroll position; `both`, `start`, and `end`
+   * force those edges on; `none` hides them.
+   * @default 'auto'
+   */
+  visibility?: ScrollShadowVisibility;
+  /**
+   * Pixels of scroll slack before an edge counts as scrollable. Only used with `auto`.
    * @default 0
    */
   offset?: number;
+  /**
+   * Hides the child's scrollbar on web. On iOS and Android, set
+   * `showsVerticalScrollIndicator` or `showsHorizontalScrollIndicator` on the child instead.
+   * @default false
+   */
+  hideScrollBar?: boolean;
+  /**
+   * Width, opacity, or position overrides for the fade overlays, applied after `size`, for
+   * example `w-24` or `opacity-85`. Must not carry color classes; use `surface` or
+   * `colorClassName` instead.
+   */
+  edgeClassName?: string;
+  /**
+   * One-off fade color outside the `surface` options, as an `accent-*` class. Overrides
+   * `surface` on every platform and follows dark mode and `ScopedTheme`.
+   */
+  colorClassName?: string;
+  /**
+   * Called when either edge starts or stops being scrollable, with
+   * `{ canScrollBefore, canScrollAfter }`. Only fires with `visibility="auto"`.
+   */
   onCapabilityChange?: (capability: ScrollShadowCapability) => void;
-  style?: ViewStyle;
 }
 
 interface ScrollShadowChildProps {
   className?: string;
-  style?: ViewStyle;
-  onLayout?: (event: Parameters<ReturnType<typeof useScrollShadow>['handleLayout']>[0]) => void;
+  horizontal?: boolean;
+  style?: StyleProp<ViewStyle>;
+  scrollEventThrottle?: number;
+  onLayout?: (event: Parameters<UseScrollShadowReturn['handleLayout']>[0]) => void;
   onContentSizeChange?: (width: number, height: number) => void;
-  onScroll?: (event: Parameters<ReturnType<typeof useScrollShadow>['handleScroll']>[0]) => void;
+  onScroll?: unknown;
   ref?: React.Ref<unknown>;
 }
 
+interface ScrollShadowEdgeProps {
+  edge: 'start' | 'end';
+  orientation: 'horizontal' | 'vertical';
+  size: ScrollShadowSize;
+  surface: ScrollShadowSurface;
+  colorClassName?: string;
+  edgeClassName?: string;
+  opacity?: Animated.Value;
+}
+
+function ScrollShadowEdge({
+  edge,
+  orientation,
+  size,
+  surface,
+  colorClassName,
+  edgeClassName,
+  opacity,
+}: ScrollShadowEdgeProps) {
+  const surfaceColor = useCSSVariable(SCROLL_SHADOW_SURFACE_CSS_VARS[surface]) || 'transparent';
+  const resolvedColorClassName = useResolveClassNames(colorClassName ?? '');
+  const customColor =
+    colorClassName != null
+      ? (resolvedColorClassName.accentColor ?? resolvedColorClassName.backgroundColor)
+      : undefined;
+
+  if (__DEV__ && colorClassName != null && customColor == null) {
+    console.warn(
+      `[ScrollShadow] colorClassName "${colorClassName}" did not resolve to a color. Falling back to surface="${surface}".`,
+    );
+  }
+
+  const isWeb = Platform.OS === 'web';
+  // Web paints built-in surfaces with static classes; a custom color has no static class,
+  // so it takes a CSS background-image (experimental_backgroundImage paints nothing on RNW).
+  const useInlinePath = !isWeb || customColor != null;
+  const inlineGradient = useInlinePath
+    ? getInlineBackgroundImage(String(customColor ?? surfaceColor), orientation, edge, false)
+    : undefined;
+  const webGradientClasses = useInlinePath
+    ? undefined
+    : getWebSurfaceGradientClasses(surface, orientation, edge);
+  const inlineStyle = inlineGradient
+    ? isWeb
+      ? ({ backgroundImage: inlineGradient } as unknown as ViewStyle)
+      : { experimental_backgroundImage: inlineGradient }
+    : undefined;
+
+  const edgeView = (
+    <View
+      pointerEvents="none"
+      accessible={false}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      aria-hidden
+      className={cn(
+        scrollShadowEdgeVariants({ orientation, edge, size }),
+        // The inline gradient is authored LTR; mirroring follows Uniwind's layout
+        // direction (I18nManager or LayoutDirection) without a re-render.
+        useInlinePath && orientation === 'horizontal' ? 'rtl:-scale-x-100' : undefined,
+        webGradientClasses,
+        edgeClassName,
+      )}
+      style={inlineStyle}
+      {...mergeDataAttributes(dataAttributes({ slot: 'scroll-shadow-edge', edge }))}
+    />
+  );
+
+  if (!opacity) {
+    return edgeView;
+  }
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      accessible={false}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      aria-hidden
+      style={[StyleSheet.absoluteFill, { opacity }]}
+    >
+      {edgeView}
+    </Animated.View>
+  );
+}
+
+function shouldShowEdge(
+  visibility: ScrollShadowVisibility,
+  edge: 'start' | 'end',
+  capability: ScrollShadowCapability,
+): boolean {
+  switch (visibility) {
+    case 'both':
+      return true;
+    case 'start':
+      return edge === 'start';
+    case 'end':
+      return edge === 'end';
+    case 'none':
+      return false;
+    case 'auto':
+    default:
+      return edge === 'start' ? capability.canScrollBefore : capability.canScrollAfter;
+  }
+}
+
+function ReanimatedTrackedChild({
+  child,
+  handleScroll,
+  trackedChildProps,
+}: {
+  child: ReactElement<ScrollShadowChildProps>;
+  handleScroll: UseScrollShadowReturn['handleScroll'];
+  trackedChildProps: ScrollShadowChildProps;
+}) {
+  const onScroll = useReanimatedComposedScrollHandler(handleScroll, child.props.onScroll);
+
+  return cloneElement(child, {
+    ...trackedChildProps,
+    onScroll,
+  });
+}
+
 export function ScrollShadow({
   children,
   className,
-  fadeFromClassName = 'from-background/35',
+  style,
+  surface = 'background',
+  size = 'default',
+  visibility = 'auto',
   hideScrollBar = false,
-  orientation = 'horizontal',
+  orientation,
   offset = 0,
+  edgeClassName,
+  colorClassName,
   onCapabilityChange,
-  size = 64,
-  style,
 }: ScrollShadowProps) {
-  const resolvedOrientation = orientation ?? 'horizontal';
   const child = Children.only(children);
 
   if (!isValidElement<ScrollShadowChildProps>(child)) {
     throw new Error('ScrollShadow expects a single React element child.');
   }
 
-  const { capability, handleContentSizeChange, handleLayout, handleScroll } = useScrollShadow({
-    offset,
-    onCapabilityChange,
-    orientation: resolvedOrientation,
-  });
+  const resolvedOrientation = orientation ?? (child.props.horizontal ? 'horizontal' : 'vertical');
+  const trackingEnabled = visibility === 'auto';
+
+  const startOpacity = useRef(new Animated.Value(0)).current;
+  const endOpacity = useRef(new Animated.Value(0)).current;
+  const fadeDistance = SCROLL_SHADOW_SIZE_PX[size];
 
-  const overlayFade = cn(fadeFromClassName, 'to-transparent');
-  const overlayAxisSize = resolvedOrientation === 'horizontal' ? { width: size } : { height: size };
+  // Opacity tracks the distance to each edge, so the fade eases out over the last
+  // `fadeDistance` px of scroll instead of cutting when the edge is reached.
+  const handleDistanceChange = useCallback(
+    ({ before, after }: ScrollShadowDistance) => {
+      startOpacity.setValue(Math.min(1, before / fadeDistance));
+      endOpacity.setValue(Math.min(1, after / fadeDistance));
+    },
+    [startOpacity, endOpacity, fadeDistance],
+  );
+
+  const { capability, handleContentSizeChange, handleLayout, handleScroll } =
+    useScrollShadowTracker({
+      offset,
+      onCapabilityChange,
+      onDistanceChange: handleDistanceChange,
+      orientation: resolvedOrientation,
+      enabled: trackingEnabled,
+    });
+
+  const showStart = shouldShowEdge(visibility, 'start', capability);
+  const showEnd = shouldShowEdge(visibility, 'end', capability);
+  const useReanimatedScroll = isReanimatedScrollHandler(child.props.onScroll);
+
+  const trackedChildProps: ScrollShadowChildProps = {
+    className: cn(scrollShadowVariants({ hideScrollBar }), child.props.className),
+    // Keep measuring while visibility is forced so a switch back to auto fades
+    // from the scroll position the user already reached.
+    onContentSizeChange: (width: number, height: number) => {
+      handleContentSizeChange(width, height);
+      child.props.onContentSizeChange?.(width, height);
+    },
+    onLayout: (event) => {
+      handleLayout(event);
+      child.props.onLayout?.(event);
+    },
+    ...(useReanimatedScroll
+      ? {}
+      : {
+          onScroll: composeScrollHandler(handleScroll, child.props.onScroll),
+        }),
+    ...(child.props.scrollEventThrottle === undefined ? { scrollEventThrottle: 16 } : {}),
+  };
 
   return (
-    <View className={cn(scrollShadowContainerVariants(), className)} style={style}>
-      {cloneElement(child, {
-        className: cn(scrollShadowVariants({ hideScrollBar }), child.props.className),
-        onContentSizeChange: (width: number, height: number) => {
-          handleContentSizeChange(width, height);
-          child.props.onContentSizeChange?.(width, height);
-        },
-        onLayout: (event) => {
-          handleLayout(event);
-          child.props.onLayout?.(event);
-        },
-        onScroll: (event) => {
-          handleScroll(event);
-          child.props.onScroll?.(event);
-        },
-        style: StyleSheet.flatten([child.props.style]),
-      })}
-      {capability.canScrollBefore ? (
-        <View
-          pointerEvents="none"
-          className={cn(
-            scrollShadowOverlayVariants({
-              orientation: resolvedOrientation,
-              edge: 'start',
-            }),
-            overlayFade,
-          )}
-          style={overlayAxisSize}
+    <View
+      className={cn(scrollShadowContainerVariants(), className)}
+      style={style}
+      {...mergeDataAttributes(dataAttributes({ slot: 'scroll-shadow' }))}
+    >
+      {useReanimatedScroll ? (
+        <ReanimatedTrackedChild
+          child={child}
+          handleScroll={handleScroll}
+          trackedChildProps={trackedChildProps}
+        />
+      ) : (
+        cloneElement(child, trackedChildProps)
+      )}
+      {showStart ? (
+        <ScrollShadowEdge
+          colorClassName={colorClassName}
+          edge="start"
+          edgeClassName={edgeClassName}
+          opacity={trackingEnabled ? startOpacity : undefined}
+          orientation={resolvedOrientation}
+          size={size}
+          surface={surface}
         />
       ) : null}
-      {capability.canScrollAfter ? (
-        <View
-          pointerEvents="none"
-          className={cn(
-            scrollShadowOverlayVariants({
-              orientation: resolvedOrientation,
-              edge: 'end',
-            }),
-            overlayFade,
-          )}
-          style={overlayAxisSize}
+      {showEnd ? (
+        <ScrollShadowEdge
+          colorClassName={colorClassName}
+          edge="end"
+          edgeClassName={edgeClassName}
+          opacity={trackingEnabled ? endOpacity : undefined}
+          orientation={resolvedOrientation}
+          size={size}
+          surface={surface}
         />
       ) : null}
     </View>
   );
 }
+
+ScrollShadow.displayName = 'ScrollShadow';

package/src/components/ScrollShadow/styles.ts

@@ -1,57 +1,74 @@
 import { cva, type VariantProps } from '@cdx-ui/utils';
 
+export type ScrollShadowSurface = 'background' | 'primary' | 'secondary';
+export type ScrollShadowSize = 'small' | 'default' | 'large';
+
+export const SCROLL_SHADOW_SURFACE_CSS_VARS: Record<ScrollShadowSurface, string> = {
+  background: '--color-surface-background',
+  primary: '--color-surface-primary',
+  secondary: '--color-surface-secondary',
+};
+
+export const SCROLL_SHADOW_SIZE_PX: Record<ScrollShadowSize, number> = {
+  small: 32,
+  default: 40,
+  large: 72,
+};
+
+export const SCROLL_SHADOW_SURFACE_FROM_CLASS: Record<ScrollShadowSurface, string> = {
+  background: 'from-surface-background',
+  primary: 'from-surface-primary',
+  secondary: 'from-surface-secondary',
+};
+
 export const scrollShadowVariants = cva([], {
   variants: {
-    orientation: {
-      horizontal: '',
-      vertical: '',
-    },
     hideScrollBar: {
       true: 'web:[scrollbar-width:none] web:[&::-webkit-scrollbar]:hidden',
       false: '',
     },
   },
   defaultVariants: {
-    orientation: 'horizontal',
     hideScrollBar: false,
   },
 });
 
 export const scrollShadowContainerVariants = cva('relative min-w-0 w-full');
 
-export const scrollShadowOverlayVariants = cva('pointer-events-none absolute z-10', {
+export const scrollShadowEdgeVariants = cva('pointer-events-none absolute z-10', {
   variants: {
     orientation: {
-      horizontal: '',
-      vertical: '',
+      horizontal: 'top-0 bottom-0',
+      vertical: 'start-0 end-0',
     },
     edge: {
       start: '',
       end: '',
     },
+    size: {
+      small: '',
+      default: '',
+      large: '',
+    },
   },
   compoundVariants: [
-    {
-      orientation: 'horizontal',
-      edge: 'start',
-      className: 'left-0 top-0 bottom-0 bg-gradient-to-r',
-    },
-    {
-      orientation: 'horizontal',
-      edge: 'end',
-      className: 'right-0 top-0 bottom-0 bg-gradient-to-l',
-    },
-    {
-      orientation: 'vertical',
-      edge: 'start',
-      className: 'left-0 right-0 top-0 bg-gradient-to-b',
-    },
-    {
-      orientation: 'vertical',
-      edge: 'end',
-      className: 'left-0 right-0 bottom-0 bg-gradient-to-t',
-    },
+    { orientation: 'horizontal', edge: 'start', className: 'start-0' },
+    { orientation: 'horizontal', edge: 'end', className: 'end-0' },
+    { orientation: 'vertical', edge: 'start', className: 'top-0' },
+    { orientation: 'vertical', edge: 'end', className: 'bottom-0' },
+    { orientation: 'horizontal', size: 'small', className: 'w-8' },
+    { orientation: 'horizontal', size: 'default', className: 'w-10' },
+    { orientation: 'horizontal', size: 'large', className: 'w-18' },
+    { orientation: 'vertical', size: 'small', className: 'h-8' },
+    { orientation: 'vertical', size: 'default', className: 'h-10' },
+    { orientation: 'vertical', size: 'large', className: 'h-18' },
   ],
+  defaultVariants: {
+    orientation: 'vertical',
+    edge: 'start',
+    size: 'default',
+  },
 });
 
 export type ScrollShadowVariantProps = VariantProps<typeof scrollShadowVariants>;
+export type ScrollShadowEdgeVariantProps = VariantProps<typeof scrollShadowEdgeVariants>;

package/src/components/ScrollShadow/useComposedScrollHandler.ts

@@ -0,0 +1,58 @@
+import { useRef } from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+import { useAnimatedScrollHandler, useComposedEventHandler } from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+import { composeEventHandlers } from '@cdx-ui/utils';
+
+type ScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+
+export function isReanimatedScrollHandler(handler: unknown): boolean {
+  return handler != null && typeof handler !== 'function';
+}
+
+export function composeScrollHandler(
+  internalHandler: ScrollHandler,
+  externalHandler: unknown,
+): ScrollHandler {
+  if (typeof externalHandler === 'function') {
+    return composeEventHandlers(internalHandler, externalHandler as ScrollHandler);
+  }
+
+  return internalHandler;
+}
+
+/**
+ * Only call this when the child already passed a Reanimated scroll handler.
+ * `useAnimatedScrollHandler` requires a Babel worklet, and the published
+ * package is not transformed by that plugin, so the plain ScrollView path
+ * must not mount this hook.
+ */
+export function useReanimatedComposedScrollHandler(
+  internalHandler: ScrollHandler,
+  externalHandler: unknown,
+): unknown {
+  const internalHandlerRef = useRef(internalHandler);
+  internalHandlerRef.current = internalHandler;
+
+  const internalAnimatedHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      'worklet';
+      // The UI-thread event is a host object. Copy the numbers scheduleOnRN can
+      // serialize; passing the event itself drops contentOffset and contentSize.
+      const { contentOffset, contentSize, layoutMeasurement } = event;
+
+      scheduleOnRN(internalHandlerRef.current, {
+        nativeEvent: {
+          contentOffset: { x: contentOffset.x, y: contentOffset.y },
+          contentSize: { width: contentSize.width, height: contentSize.height },
+          layoutMeasurement: {
+            width: layoutMeasurement.width,
+            height: layoutMeasurement.height,
+          },
+        },
+      } as NativeSyntheticEvent<NativeScrollEvent>);
+    },
+  });
+
+  return useComposedEventHandler([externalHandler as never, internalAnimatedHandler]);
+}