@idealyst/components 1.2.123 → 1.2.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.2.123",
+  "version": "1.2.124",
   "description": "Shared component library for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/components#readme",
   "readme": "README.md",
@@ -56,7 +56,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.2.123",
+    "@idealyst/theme": "^1.2.124",
     "@mdi/js": ">=7.0.0",
     "@mdi/react": ">=1.0.0",
     "@react-native-vector-icons/common": ">=12.0.0",
@@ -111,8 +111,8 @@
   },
   "devDependencies": {
     "@idealyst/blur": "^1.2.40",
-    "@idealyst/theme": "^1.2.123",
-    "@idealyst/tooling": "^1.2.123",
+    "@idealyst/theme": "^1.2.124",
+    "@idealyst/tooling": "^1.2.124",
     "@mdi/react": "^1.6.1",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",

package/src/ScrollView/ScrollView.native.tsx

@@ -0,0 +1,172 @@
+import { forwardRef, useCallback, useImperativeHandle, useRef } from 'react';
+import {
+  ScrollView as RNScrollView,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+  ViewStyle,
+} from 'react-native';
+import { scrollViewStyles } from './ScrollView.styles';
+import type { ScrollViewProps, ScrollViewRef, ScrollEvent } from './types';
+import type { IdealystElement } from '../utils/refTypes';
+
+function buildScrollEvent(e: NativeScrollEvent): ScrollEvent {
+  const { contentOffset, contentSize, layoutMeasurement } = e;
+  const isVerticalEnd =
+    contentOffset.y + layoutMeasurement.height >= contentSize.height - 1;
+  const isHorizontalEnd =
+    contentOffset.x + layoutMeasurement.width >= contentSize.width - 1;
+
+  return {
+    position: { x: contentOffset.x, y: contentOffset.y },
+    contentSize: { width: contentSize.width, height: contentSize.height },
+    layoutSize: { width: layoutMeasurement.width, height: layoutMeasurement.height },
+    isAtEnd: isVerticalEnd || isHorizontalEnd,
+    isAtStart: contentOffset.x <= 0 && contentOffset.y <= 0,
+  };
+}
+
+const ScrollView = forwardRef<ScrollViewRef, ScrollViewProps>(({
+  children,
+  direction = 'vertical',
+  background = 'transparent',
+  radius = 'none',
+  border = 'none',
+  gap,
+  padding,
+  paddingVertical,
+  paddingHorizontal,
+  margin,
+  marginVertical,
+  marginHorizontal,
+  backgroundColor,
+  borderRadius,
+  borderWidth,
+  borderColor,
+  style,
+  contentContainerStyle,
+  showsIndicator = true,
+  pagingEnabled = false,
+  bounces = true,
+  onScroll,
+  onScrollBegin,
+  onScrollEnd,
+  onEndReached,
+  onEndReachedThreshold = 0,
+  scrollEventThrottle = 16,
+  scrollEnabled = true,
+  keyboardDismissMode = 'none',
+  testID,
+  id,
+  onLayout,
+}, ref) => {
+  const scrollRef = useRef<RNScrollView>(null);
+  const lastPositionRef = useRef({ x: 0, y: 0 });
+  const endReachedRef = useRef(false);
+
+  const backgroundVariant = background === 'transparent' ? undefined : background;
+
+  scrollViewStyles.useVariants({
+    background: backgroundVariant,
+    radius,
+    border,
+    gap,
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    margin,
+    marginVertical,
+    marginHorizontal,
+  });
+
+  const containerStyle = (scrollViewStyles.container as any)({});
+  const contentStyle = (scrollViewStyles.contentContainer as any)({});
+
+  const overrideStyles: ViewStyle = {};
+  if (backgroundColor) overrideStyles.backgroundColor = backgroundColor;
+  if (borderRadius !== undefined) overrideStyles.borderRadius = borderRadius;
+  if (borderWidth !== undefined) overrideStyles.borderWidth = borderWidth;
+  if (borderColor) overrideStyles.borderColor = borderColor;
+
+  // Imperative handle
+  useImperativeHandle(ref, () => ({
+    scrollTo: (options) => {
+      scrollRef.current?.scrollTo({
+        x: options.x ?? 0,
+        y: options.y ?? 0,
+        animated: options.animated ?? true,
+      });
+    },
+    scrollToEnd: (options) => {
+      scrollRef.current?.scrollToEnd({ animated: options?.animated ?? true });
+    },
+    scrollToStart: (options) => {
+      scrollRef.current?.scrollTo({
+        x: 0,
+        y: 0,
+        animated: options?.animated ?? true,
+      });
+    },
+    getScrollPosition: () => lastPositionRef.current,
+    getInnerElement: () => scrollRef.current,
+  }), []);
+
+  const handleScroll = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const event = buildScrollEvent(e.nativeEvent);
+    lastPositionRef.current = event.position;
+
+    onScroll?.(event);
+
+    // End reached detection
+    if (onEndReached) {
+      const { contentOffset, contentSize, layoutMeasurement } = e.nativeEvent;
+      const distanceFromEnd = direction === 'horizontal'
+        ? contentSize.width - layoutMeasurement.width - contentOffset.x
+        : contentSize.height - layoutMeasurement.height - contentOffset.y;
+
+      if (distanceFromEnd <= onEndReachedThreshold && !endReachedRef.current) {
+        endReachedRef.current = true;
+        onEndReached();
+      } else if (distanceFromEnd > onEndReachedThreshold) {
+        endReachedRef.current = false;
+      }
+    }
+  }, [onScroll, onEndReached, onEndReachedThreshold, direction]);
+
+  const handleScrollBeginDrag = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    onScrollBegin?.(buildScrollEvent(e.nativeEvent));
+  }, [onScrollBegin]);
+
+  const handleMomentumScrollEnd = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    onScrollEnd?.(buildScrollEvent(e.nativeEvent));
+  }, [onScrollEnd]);
+
+  const isHorizontal = direction === 'horizontal';
+
+  return (
+    <RNScrollView
+      ref={scrollRef}
+      style={[containerStyle, overrideStyles, style]}
+      contentContainerStyle={[contentStyle, contentContainerStyle]}
+      horizontal={isHorizontal}
+      showsVerticalScrollIndicator={!isHorizontal && showsIndicator}
+      showsHorizontalScrollIndicator={isHorizontal && showsIndicator}
+      pagingEnabled={pagingEnabled}
+      bounces={bounces}
+      scrollEnabled={scrollEnabled}
+      scrollEventThrottle={scrollEventThrottle}
+      keyboardDismissMode={keyboardDismissMode}
+      onScroll={handleScroll}
+      onScrollBeginDrag={onScrollBegin ? handleScrollBeginDrag : undefined}
+      onMomentumScrollEnd={onScrollEnd ? handleMomentumScrollEnd : undefined}
+      onLayout={onLayout}
+      testID={testID}
+      nativeID={id}
+    >
+      {children}
+    </RNScrollView>
+  );
+});
+
+ScrollView.displayName = 'ScrollView';
+
+export default ScrollView;

package/src/ScrollView/ScrollView.styles.tsx

@@ -0,0 +1,104 @@
+/**
+ * ScrollView styles using defineStyle with $iterator expansion.
+ * Reuses the same visual variant patterns as View.
+ */
+import { StyleSheet } from 'react-native-unistyles';
+import { defineStyle, ThemeStyleWrapper } from '@idealyst/theme';
+import type { Theme as BaseTheme } from '@idealyst/theme';
+import { ScrollViewBackgroundVariant, ScrollViewBorderVariant, ScrollViewRadiusVariant } from './types';
+import { ViewStyleSize } from '../utils/viewStyleProps';
+
+// Required: Unistyles must see StyleSheet usage in original source to process this file
+void StyleSheet;
+
+// Wrap theme for $iterator support
+type Theme = ThemeStyleWrapper<BaseTheme>;
+
+export type ScrollViewVariants = {
+    background: ScrollViewBackgroundVariant;
+    radius: ScrollViewRadiusVariant;
+    border: ScrollViewBorderVariant;
+    gap: ViewStyleSize;
+    padding: ViewStyleSize;
+    paddingVertical: ViewStyleSize;
+    paddingHorizontal: ViewStyleSize;
+    margin: ViewStyleSize;
+    marginVertical: ViewStyleSize;
+    marginHorizontal: ViewStyleSize;
+};
+
+export type ScrollViewDynamicProps = Partial<ScrollViewVariants>;
+
+export const scrollViewStyles = defineStyle('ScrollView', (theme: Theme) => ({
+    container: (_props: ScrollViewDynamicProps) => ({
+        display: 'flex' as const,
+        flex: 1,
+        borderColor: theme.colors.border.primary,
+        borderWidth: 0,
+        variants: {
+            background: {
+                backgroundColor: theme.colors.$surface,
+            },
+            radius: {
+                none: { borderRadius: 0 },
+                xs: { borderRadius: 2 },
+                sm: { borderRadius: 4 },
+                md: { borderRadius: 8 },
+                lg: { borderRadius: 12 },
+                xl: { borderRadius: 16 },
+            },
+            border: {
+                none: { borderWidth: 0 },
+                thin: { borderWidth: 1, borderStyle: 'solid' as const, borderColor: theme.colors.pallet.gray[300] },
+                thick: { borderWidth: 2, borderStyle: 'solid' as const, borderColor: theme.colors.pallet.gray[300] },
+            },
+            margin: {
+                margin: theme.sizes.$view.padding,
+            },
+            marginVertical: {
+                marginVertical: theme.sizes.$view.padding,
+            },
+            marginHorizontal: {
+                marginHorizontal: theme.sizes.$view.padding,
+            },
+        },
+        _web: {
+            display: 'flex',
+            flexDirection: 'column',
+            boxSizing: 'border-box',
+            borderStyle: 'solid',
+            position: 'relative',
+            minHeight: 0,
+        },
+    }),
+    contentContainer: (_props: ScrollViewDynamicProps) => ({
+        borderColor: theme.colors.border.primary,
+        borderWidth: 0,
+        variants: {
+            gap: {
+                gap: theme.sizes.$view.spacing,
+            },
+            padding: {
+                padding: theme.sizes.$view.padding,
+            },
+            paddingVertical: {
+                paddingVertical: theme.sizes.$view.padding,
+            },
+            paddingHorizontal: {
+                paddingHorizontal: theme.sizes.$view.padding,
+            },
+        },
+        _web: {
+            boxSizing: 'border-box',
+        },
+    }),
+    // Web-only: the actual scrolling element (absolute positioned within container)
+    scrollableRegion: {
+        _web: {
+            position: 'absolute',
+            inset: 0,
+            overflow: 'auto',
+            boxSizing: 'border-box',
+        },
+    },
+}));

package/src/ScrollView/ScrollView.web.tsx

@@ -0,0 +1,242 @@
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useRef } from 'react';
+import { getWebProps } from 'react-native-unistyles/web';
+import { scrollViewStyles } from './ScrollView.styles';
+import type { ScrollViewProps, ScrollViewRef, ScrollEvent } from './types';
+import useMergeRefs from '../hooks/useMergeRefs';
+import { useWebLayout } from '../hooks/useWebLayout';
+import { flattenStyle } from '../utils/flattenStyle';
+import type { IdealystElement } from '../utils/refTypes';
+
+function buildScrollEvent(el: HTMLElement): ScrollEvent {
+  const position = { x: el.scrollLeft, y: el.scrollTop };
+  const contentSize = { width: el.scrollWidth, height: el.scrollHeight };
+  const layoutSize = { width: el.clientWidth, height: el.clientHeight };
+  const isAtEnd =
+    el.scrollTop + el.clientHeight >= el.scrollHeight - 1 ||
+    el.scrollLeft + el.clientWidth >= el.scrollWidth - 1;
+  const isAtStart = el.scrollLeft <= 0 && el.scrollTop <= 0;
+
+  return { position, contentSize, layoutSize, isAtEnd, isAtStart };
+}
+
+/**
+ * Scrollable container with scroll event abstractions and imperative scroll controls.
+ * Web implementation uses a container + absolutely positioned scrollable region.
+ */
+const ScrollView = forwardRef<ScrollViewRef, ScrollViewProps>(({
+  children,
+  direction = 'vertical',
+  background = 'transparent',
+  radius = 'none',
+  border = 'none',
+  gap,
+  padding,
+  paddingVertical,
+  paddingHorizontal,
+  margin,
+  marginVertical,
+  marginHorizontal,
+  backgroundColor: _backgroundColor,
+  borderRadius: _borderRadius,
+  borderWidth: _borderWidth,
+  borderColor: _borderColor,
+  style,
+  contentContainerStyle,
+  showsIndicator = true,
+  onScroll,
+  onScrollBegin,
+  onScrollEnd,
+  onEndReached,
+  onEndReachedThreshold = 0,
+  scrollEnabled = true,
+  testID,
+  id,
+  onLayout,
+}, ref) => {
+  const scrollElRef = useRef<HTMLDivElement>(null);
+  const isDraggingRef = useRef(false);
+  const scrollTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+  const endReachedRef = useRef(false);
+  const layoutRef = useWebLayout<HTMLDivElement>(onLayout);
+
+  const backgroundVariant = background === 'transparent' ? undefined : background;
+
+  scrollViewStyles.useVariants({
+    background: backgroundVariant,
+    radius,
+    border,
+    gap,
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    margin,
+    marginVertical,
+    marginHorizontal,
+  });
+
+  /** @ts-ignore */
+  const containerWebProps = getWebProps((scrollViewStyles.container as any)({}));
+  /** @ts-ignore */
+  const scrollRegionWebProps = getWebProps(scrollViewStyles.scrollableRegion);
+  /** @ts-ignore */
+  const contentWebProps = getWebProps((scrollViewStyles.contentContainer as any)({}));
+
+  // Imperative handle
+  useImperativeHandle(ref, () => ({
+    scrollTo: (options) => {
+      scrollElRef.current?.scrollTo({
+        left: options.x ?? 0,
+        top: options.y ?? 0,
+        behavior: (options.animated ?? true) ? 'smooth' : 'instant',
+      });
+    },
+    scrollToEnd: (options) => {
+      const el = scrollElRef.current;
+      if (!el) return;
+      const behavior = (options?.animated ?? true) ? 'smooth' : 'instant';
+      if (direction === 'horizontal') {
+        el.scrollTo({ left: el.scrollWidth, behavior });
+      } else {
+        el.scrollTo({ top: el.scrollHeight, behavior });
+      }
+    },
+    scrollToStart: (options) => {
+      scrollElRef.current?.scrollTo({
+        left: 0,
+        top: 0,
+        behavior: (options?.animated ?? true) ? 'smooth' : 'instant',
+      });
+    },
+    getScrollPosition: () => {
+      const el = scrollElRef.current;
+      return { x: el?.scrollLeft ?? 0, y: el?.scrollTop ?? 0 };
+    },
+    getInnerElement: () => scrollElRef.current,
+  }), [direction]);
+
+  // Scroll event handling
+  const handleScroll = useCallback(() => {
+    const el = scrollElRef.current;
+    if (!el) return;
+
+    const event = buildScrollEvent(el);
+    onScroll?.(event);
+
+    // Scroll begin detection (first scroll after idle)
+    if (!isDraggingRef.current) {
+      isDraggingRef.current = true;
+      onScrollBegin?.(event);
+    }
+
+    // Scroll end detection via timeout
+    if (scrollTimeoutRef.current) clearTimeout(scrollTimeoutRef.current);
+    scrollTimeoutRef.current = setTimeout(() => {
+      isDraggingRef.current = false;
+      if (el) onScrollEnd?.(buildScrollEvent(el));
+    }, 150);
+
+    // End reached detection
+    if (onEndReached) {
+      const distanceFromEnd = direction === 'horizontal'
+        ? el.scrollWidth - el.clientWidth - el.scrollLeft
+        : el.scrollHeight - el.clientHeight - el.scrollTop;
+
+      if (distanceFromEnd <= onEndReachedThreshold && !endReachedRef.current) {
+        endReachedRef.current = true;
+        onEndReached();
+      } else if (distanceFromEnd > onEndReachedThreshold) {
+        endReachedRef.current = false;
+      }
+    }
+  }, [onScroll, onScrollBegin, onScrollEnd, onEndReached, onEndReachedThreshold, direction]);
+
+  // Attach scroll listener
+  useEffect(() => {
+    const el = scrollElRef.current;
+    if (!el) return;
+    el.addEventListener('scroll', handleScroll, { passive: true });
+    return () => {
+      el.removeEventListener('scroll', handleScroll);
+      if (scrollTimeoutRef.current) clearTimeout(scrollTimeoutRef.current);
+    };
+  }, [handleScroll]);
+
+  const mergedRef = useMergeRefs(layoutRef, containerWebProps.ref);
+
+  const flatStyle = flattenStyle(style);
+  const flatContentStyle = flattenStyle(contentContainerStyle);
+
+  // Split user styles: sizing/margin to container, visual to content
+  const {
+    width, height, minWidth, minHeight, maxWidth, maxHeight,
+    flex, flexGrow, flexShrink, flexBasis, alignSelf,
+    margin: userMargin, marginTop, marginRight, marginBottom, marginLeft,
+    marginBlock, marginInline,
+    ...restStyle
+  } = flatStyle;
+
+  const containerUserStyles: React.CSSProperties = {
+    ...(width !== undefined && { width }),
+    ...(height !== undefined && { height }),
+    ...(minWidth !== undefined && { minWidth }),
+    ...(minHeight !== undefined && { minHeight }),
+    ...(maxWidth !== undefined && { maxWidth }),
+    ...(maxHeight !== undefined && { maxHeight }),
+    ...(flex !== undefined && { flex }),
+    ...(flexGrow !== undefined && { flexGrow }),
+    ...(flexShrink !== undefined && { flexShrink }),
+    ...(flexBasis !== undefined && { flexBasis }),
+    ...(alignSelf !== undefined && { alignSelf }),
+    ...(userMargin !== undefined && { margin: userMargin }),
+    ...(marginTop !== undefined && { marginTop }),
+    ...(marginRight !== undefined && { marginRight }),
+    ...(marginBottom !== undefined && { marginBottom }),
+    ...(marginLeft !== undefined && { marginLeft }),
+    ...(marginBlock !== undefined && { marginBlock }),
+    ...(marginInline !== undefined && { marginInline }),
+  };
+
+  // Determine overflow direction
+  const overflowX = direction === 'horizontal' || direction === 'both' ? 'auto' : 'hidden';
+  const overflowY = direction === 'vertical' || direction === 'both' ? 'auto' : 'hidden';
+
+  // Hide scrollbar CSS
+  const scrollbarStyle: React.CSSProperties = showsIndicator ? {} : {
+    scrollbarWidth: 'none',
+  };
+
+  return (
+    <div
+      {...containerWebProps}
+      style={containerUserStyles}
+      ref={mergedRef}
+      id={id}
+      data-testid={testID}
+    >
+      <div
+        {...scrollRegionWebProps}
+        ref={scrollElRef}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          overflowX: scrollEnabled ? overflowX : 'hidden',
+          overflowY: scrollEnabled ? overflowY : 'hidden',
+          boxSizing: 'border-box',
+          ...scrollbarStyle,
+          ...restStyle,
+        }}
+      >
+        <div
+          {...contentWebProps}
+          style={flatContentStyle}
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+});
+
+ScrollView.displayName = 'ScrollView';
+
+export default ScrollView;

package/src/ScrollView/docs.ts

@@ -0,0 +1,9 @@
+/**
+ * ScrollView Documentation Sample Props
+ */
+
+import type { SampleProps } from '@idealyst/tooling';
+
+export const sampleProps: SampleProps = {
+  children: 'Scrollable content',
+};

package/src/ScrollView/index.native.ts

@@ -0,0 +1,2 @@
+export { default } from './ScrollView.native';
+export * from './types';

package/src/ScrollView/index.ts

@@ -0,0 +1,5 @@
+import ScrollViewComponent from './ScrollView.web';
+
+export default ScrollViewComponent;
+export { ScrollViewComponent as ScrollView };
+export * from './types';

package/src/ScrollView/index.web.ts

@@ -0,0 +1,5 @@
+import ScrollViewComponent from './ScrollView.web';
+
+export default ScrollViewComponent;
+export { ScrollViewComponent as ScrollView };
+export * from './types';

package/src/ScrollView/types.ts

@@ -0,0 +1,169 @@
+import { Size, Surface } from '@idealyst/theme';
+import type { ReactNode, RefObject } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { ContainerStyleProps } from '../utils/viewStyleProps';
+import type { LayoutChangeEvent } from '../hooks/useWebLayout';
+
+export type { LayoutChangeEvent };
+
+// Component-specific type aliases
+export type ScrollViewBackgroundVariant = Surface | 'transparent';
+export type ScrollViewRadiusVariant = Size | 'none';
+export type ScrollViewBorderVariant = 'none' | 'thin' | 'thick';
+export type ScrollViewDirection = 'vertical' | 'horizontal' | 'both';
+
+/**
+ * Scroll position information.
+ */
+export interface ScrollPosition {
+  x: number;
+  y: number;
+}
+
+/**
+ * Content size information for the scrollable content.
+ */
+export interface ScrollContentSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Layout size of the scroll view container.
+ */
+export interface ScrollLayoutSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Normalized scroll event provided to all scroll callbacks.
+ */
+export interface ScrollEvent {
+  /** Current scroll offset */
+  position: ScrollPosition;
+  /** Size of the scrollable content */
+  contentSize: ScrollContentSize;
+  /** Size of the visible scroll container */
+  layoutSize: ScrollLayoutSize;
+  /** Whether the content is scrolled to the end (vertical or horizontal depending on direction) */
+  isAtEnd: boolean;
+  /** Whether the content is scrolled to the start */
+  isAtStart: boolean;
+}
+
+/**
+ * Options for scrollTo operations.
+ */
+export interface ScrollToOptions {
+  x?: number;
+  y?: number;
+  animated?: boolean;
+}
+
+/**
+ * Imperative handle exposed via ref for controlling scroll programmatically.
+ */
+export interface ScrollViewRef {
+  /** Scroll to a specific position */
+  scrollTo: (options: ScrollToOptions) => void;
+  /** Scroll to the end of the content */
+  scrollToEnd: (options?: { animated?: boolean }) => void;
+  /** Scroll to the top/start of the content */
+  scrollToStart: (options?: { animated?: boolean }) => void;
+  /** Get current scroll position */
+  getScrollPosition: () => ScrollPosition;
+  /** Get the underlying native element */
+  getInnerElement: () => any;
+}
+
+/**
+ * Scrollable container with scroll event abstractions and imperative scroll controls.
+ */
+export interface ScrollViewProps extends ContainerStyleProps {
+  children?: ReactNode;
+
+  /** Scroll direction. Defaults to 'vertical'. */
+  direction?: ScrollViewDirection;
+
+  /** Background variant */
+  background?: ScrollViewBackgroundVariant;
+
+  /** Border radius variant */
+  radius?: ScrollViewRadiusVariant;
+
+  /** Border variant */
+  border?: ScrollViewBorderVariant;
+
+  /** Custom background color (overrides background variant) */
+  backgroundColor?: string;
+
+  /** Custom border radius (overrides radius variant) */
+  borderRadius?: number;
+
+  /** Custom border width (overrides border variant) */
+  borderWidth?: number;
+
+  /** Custom border color */
+  borderColor?: string;
+
+  /** Additional styles */
+  style?: StyleProp<ViewStyle>;
+
+  /** Styles applied to the content container */
+  contentContainerStyle?: StyleProp<ViewStyle>;
+
+  /** Whether to show scroll indicators. Defaults to true. */
+  showsIndicator?: boolean;
+
+  /** Whether to enable paging behavior */
+  pagingEnabled?: boolean;
+
+  /** Whether the scroll view bounces at the edges (iOS). Defaults to true. */
+  bounces?: boolean;
+
+  /**
+   * Called continuously as the user scrolls.
+   * Use `scrollEventThrottle` to control frequency.
+   */
+  onScroll?: (event: ScrollEvent) => void;
+
+  /**
+   * Called when scrolling begins (user starts dragging).
+   */
+  onScrollBegin?: (event: ScrollEvent) => void;
+
+  /**
+   * Called when scrolling ends (momentum settles or user lifts finger).
+   */
+  onScrollEnd?: (event: ScrollEvent) => void;
+
+  /**
+   * Called when the scroll position reaches the end of the content.
+   * Useful for infinite scroll / load-more patterns.
+   */
+  onEndReached?: () => void;
+
+  /**
+   * Distance from the end (in pixels) at which onEndReached fires.
+   * Defaults to 0.
+   */
+  onEndReachedThreshold?: number;
+
+  /**
+   * Throttle interval (ms) for onScroll events on native. Defaults to 16 (~60fps).
+   */
+  scrollEventThrottle?: number;
+
+  /** Whether scrolling is enabled. Defaults to true. */
+  scrollEnabled?: boolean;
+
+  /** Whether the keyboard should dismiss on drag. */
+  keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+
+  /** Test ID for testing */
+  testID?: string;
+
+  /** Callback when layout changes */
+  onLayout?: (event: LayoutChangeEvent) => void;
+}

package/src/TabBar/TabBar.styles.tsx

@@ -92,15 +92,15 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
     },
 
     tab: ({ type = 'standard', size = 'md', active = false, pillMode: _pillMode = 'light', disabled = false, iconPosition = 'left', justify = 'start' }: TabBarDynamicProps) => {
-        // Tab padding for pills
-        const paddingMap: Record<Size, { paddingVertical: number; paddingHorizontal: number }> = {
-            xs: { paddingVertical: 2, paddingHorizontal: 10 },
-            sm: { paddingVertical: 4, paddingHorizontal: 12 },
-            md: { paddingVertical: 6, paddingHorizontal: 16 },
-            lg: { paddingVertical: 8, paddingHorizontal: 20 },
-            xl: { paddingVertical: 10, paddingHorizontal: 24 },
+        // Tab padding for pills — narrower than standard tabs
+        const pillsPaddingMap: Record<Size, { paddingVertical: number; paddingHorizontal: number }> = {
+            xs: { paddingVertical: 2, paddingHorizontal: 8 },
+            sm: { paddingVertical: 3, paddingHorizontal: 10 },
+            md: { paddingVertical: 4, paddingHorizontal: 12 },
+            lg: { paddingVertical: 6, paddingHorizontal: 16 },
+            xl: { paddingVertical: 8, paddingHorizontal: 20 },
         };
-        const tabPadding = type === 'pills' ? paddingMap[size] : {};
+        const tabPadding = type === 'pills' ? pillsPaddingMap[size] : {};
 
         // Color based on type and active state
         let color = active ? theme.colors.text.primary : theme.colors.text.secondary;
@@ -125,13 +125,17 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
             opacity: disabled ? 0.5 : 1,
             ...tabPadding,
             variants: {
-                size: {
-                    fontSize: theme.sizes.$tabBar.fontSize,
-                    paddingHorizontal: theme.sizes.$tabBar.padding,
-                    paddingTop: theme.sizes.$tabBar.padding,
-                    paddingBottom: theme.sizes.$tabBar.paddingBottom,
-                    lineHeight: theme.sizes.$tabBar.lineHeight,
-                },
+                size: type === 'pills'
+                    ? {
+                        fontSize: theme.sizes.$tabBar.fontSize,
+                        lineHeight: theme.sizes.$tabBar.lineHeight,
+                    }
+                    : {
+                        fontSize: theme.sizes.$tabBar.fontSize,
+                        paddingVertical: theme.sizes.$tabBar.padding,
+                        paddingHorizontal: theme.sizes.$tabBar.padding,
+                        lineHeight: theme.sizes.$tabBar.lineHeight,
+                    },
             },
             _web: {
                 border: 'none',
@@ -186,8 +190,8 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
 
         const typeStyles = type === 'pills' ? {
             borderRadius: 9999,
-            bottom: 4,
-            top: 4,
+            bottom: 3,
+            top: 3,
             left: 0,
         } : {
             bottom: -1,

package/src/View/types.ts

@@ -90,6 +90,10 @@ export interface ViewProps extends ContainerStyleProps {
   style?: ViewStyleProp;
 
   /**
+   * @deprecated Use the ScrollView component instead, which provides scroll event
+   * abstractions (onScroll, onScrollBegin, onScrollEnd, onEndReached) and imperative
+   * scroll controls (scrollTo, scrollToEnd, scrollToStart) via ref.
+   *
    * Enable scrollable content.
    * - Native: Wraps children in a ScrollView
    * - Web: Renders a wrapper + content structure where the wrapper fills available

package/src/index.native.ts

@@ -10,6 +10,9 @@ export * from './Text/types';
 export { default as View } from './View';
 export * from './View/types';
 
+export { default as ScrollView } from './ScrollView';
+export * from './ScrollView/types';
+
 export { default as Pressable } from './Pressable';
 export * from './Pressable/types';
 
@@ -126,6 +129,7 @@ export type { ButtonProps } from './Button/types';
 export type { IconButtonProps } from './IconButton/types';
 export type { TextProps } from './Text/types';
 export type { ViewProps } from './View/types';
+export type { ScrollViewProps, ScrollViewRef, ScrollEvent, ScrollPosition, ScrollToOptions } from './ScrollView/types';
 export type { InputProps } from './Input/types';
 export type { TextInputProps } from './TextInput/types';
 export type { CheckboxProps } from './Checkbox/types';

package/src/index.ts

@@ -15,6 +15,9 @@ export * from './Text/types';
 export { default as View } from './View';
 export * from './View/types';
 
+export { default as ScrollView } from './ScrollView';
+export * from './ScrollView/types';
+
 export { default as Pressable } from './Pressable';
 export * from './Pressable/types';
 
@@ -134,6 +137,7 @@ export type { ButtonProps } from './Button/types';
 export type { IconButtonProps } from './IconButton/types';
 export type { TextProps } from './Text/types';
 export type { ViewProps } from './View/types';
+export type { ScrollViewProps, ScrollViewRef, ScrollEvent, ScrollPosition, ScrollToOptions } from './ScrollView/types';
 export type { LinkProps } from './Link/types';
 export type { TextInputProps } from './TextInput/types';
 /** @deprecated Use TextInputProps instead */