@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/scroll-shadow/content.md

@@ -0,0 +1,686 @@
+# ScrollShadow (https://design.candescent.com/docs/components/scroll-shadow)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-scrollshadow--default)
+
+`ScrollShadow` wraps a single scroll view and fades its edges into the surface behind it, showing a fade only on the edge that still has content.
+
+```tsx
+import { ScrollShadow } from '@cdx-ui/components';
+```
+
+> [!NOTE]
+>
+> **Wrap the scroll view directly**
+>
+> On iOS, Android, and web, `ScrollShadow` is a wrapper, not a scroll container. It doesn't scroll
+> anything itself, so you always bring your own `ScrollView`, `FlatList`, or `VirtualizedList`, and
+> it must be the direct child. `ScrollShadow` reads that child's scroll events, so a component that
+> renders a scroll view inside it gets no fades, even on web. The one exception is a forced
+> `visibility`, covered under Visibility.
+
+## Basic
+
+Put the scroll view directly inside `ScrollShadow`. Orientation is inferred from the child's `horizontal` prop and defaults to vertical. Match `surface` to the panel behind the scroller so the fade blends in.
+
+```tsx
+import {
+  Avatar,
+  Card,
+  Heading,
+  ListItem,
+  ScrollShadow,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+import { TRANSACTIONS } from './_data';
+
+export default function ScrollShadowBasicDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-sm">
+      <Card.Header>
+        <Heading size="sm">Recent activity</Heading>
+        <Text size="sm" color="secondary">
+          Checking · 6643
+        </Text>
+      </Card.Header>
+      <Card.Content>
+        <ScrollShadow className="h-80" surface="primary">
+          <ScrollView>
+            {TRANSACTIONS.map((transaction, index) => (
+              <ListItem key={transaction.id} showSeparator={index < TRANSACTIONS.length - 1}>
+                <ListItem.LeadingSlot>
+                  <Avatar color={transaction.isCredit ? 'success' : 'neutral'}>
+                    <Avatar.Icon as={transaction.icon} />
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>{transaction.merchant}</ListItem.Title>
+                  <ListItem.Description>{transaction.date}</ListItem.Description>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <Text color={transaction.isCredit ? 'success' : 'primary'}>
+                    {transaction.amount}
+                  </Text>
+                </ListItem.TrailingSlot>
+              </ListItem>
+            ))}
+          </ScrollView>
+        </ScrollShadow>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Horizontal
+
+A horizontal child gets fades on its start and end edges. Those edges are logical, not physical: in a left-to-right layout start is left and end is right; in RTL, start is right and end is left. You never pass `left` or `right`. The same `ScrollShadow` flips with the page direction. For a filter row, put a `ToggleButton.Group` with `isAttached={false}` inside the horizontal `ScrollView`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Avatar,
+  Box,
+  Card,
+  Divider,
+  Heading,
+  ListItem,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  ToggleButton,
+} from '@cdx-ui/components';
+import { ACTIVITY_FILTERS, TRANSACTIONS } from './_data';
+
+const VISIBLE_ROWS = 4;
+
+export default function ScrollShadowHorizontalDemo() {
+  const [filters, setFilters] = useState<string[]>(['purchases', 'dining']);
+
+  const matches =
+    filters.length > 0
+      ? TRANSACTIONS.filter((transaction) => filters.includes(transaction.category))
+      : TRANSACTIONS;
+  const rows = matches.slice(0, VISIBLE_ROWS);
+
+  return (
+    <Card fullBleed className="w-full max-w-sm">
+      <Card.Header>
+        <Heading size="sm">Activity</Heading>
+        <Text size="sm" color="secondary">
+          {matches.length} of {TRANSACTIONS.length}
+        </Text>
+      </Card.Header>
+      <Card.Content>
+        <Box className="py-3">
+          <ScrollShadow surface="primary" hideScrollBar>
+            <ScrollView
+              horizontal
+              showsHorizontalScrollIndicator={false}
+              contentContainerClassName="px-5"
+            >
+              <ToggleButton.Group
+                type="multiple"
+                isAttached={false}
+                value={filters}
+                onValueChange={setFilters}
+                aria-label="Filter activity by type"
+              >
+                {ACTIVITY_FILTERS.map((filter) => (
+                  <ToggleButton key={filter.value} value={filter.value} size="small">
+                    <ToggleButton.Icon as={filter.icon} position="leading" />
+                    <ToggleButton.Label>{filter.label}</ToggleButton.Label>
+                  </ToggleButton>
+                ))}
+              </ToggleButton.Group>
+            </ScrollView>
+          </ScrollShadow>
+        </Box>
+        <Divider />
+        {rows.map((transaction, index) => (
+          <ListItem key={transaction.id} showSeparator={index < rows.length - 1}>
+            <ListItem.LeadingSlot>
+              <Avatar color={transaction.isCredit ? 'success' : 'neutral'}>
+                <Avatar.Icon as={transaction.icon} />
+              </Avatar>
+            </ListItem.LeadingSlot>
+            <ListItem.Content>
+              <ListItem.Title>{transaction.merchant}</ListItem.Title>
+              <ListItem.Description>{transaction.date}</ListItem.Description>
+            </ListItem.Content>
+            <ListItem.TrailingSlot>
+              <Text color={transaction.isCredit ? 'success' : 'primary'}>{transaction.amount}</Text>
+            </ListItem.TrailingSlot>
+          </ListItem>
+        ))}
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Surfaces
+
+`surface` picks the fade color from the theme: `background`, `primary`, or `secondary`. The fade follows dark mode and `ScopedTheme`.
+
+```tsx
+import {
+  Card,
+  QuickActionButton,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  VStack,
+  type ScrollShadowProps,
+} from '@cdx-ui/components';
+import { QUICK_ACTIONS } from './_data';
+
+type Surface = NonNullable<ScrollShadowProps['surface']>;
+
+const panels: { surface: Surface; className?: string }[] = [
+  { surface: 'background', className: 'bg-surface-background' },
+  { surface: 'primary' },
+  { surface: 'secondary', className: 'bg-surface-secondary' },
+];
+
+export default function ScrollShadowSurfacesDemo() {
+  return (
+    <VStack space="lg" className="w-full max-w-sm">
+      {panels.map(({ surface, className }) => (
+        <VStack key={surface} space="xs">
+          <Text size="sm" color="secondary">
+            {surface}
+          </Text>
+          <Card fullBleed className={className}>
+            <Card.Content className="py-5">
+              <ScrollShadow surface={surface} size="large">
+                <ScrollView
+                  horizontal
+                  showsHorizontalScrollIndicator={false}
+                  contentContainerClassName="gap-4 px-5"
+                >
+                  {QUICK_ACTIONS.map((action) => (
+                    <QuickActionButton key={action.label}>
+                      <QuickActionButton.Icon as={action.icon} />
+                      <QuickActionButton.Label>{action.label}</QuickActionButton.Label>
+                    </QuickActionButton>
+                  ))}
+                </ScrollView>
+              </ScrollShadow>
+            </Card.Content>
+          </Card>
+        </VStack>
+      ))}
+    </VStack>
+  );
+}
+```
+
+## Sizes
+
+`size` sets the fade depth along the scroll axis: `small` is 32px, `default` is 40px, and `large` is 72px.
+
+```tsx
+import {
+  Avatar,
+  Card,
+  Divider,
+  Heading,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  VStack,
+  type AvatarColor,
+  type ScrollShadowProps,
+} from '@cdx-ui/components';
+import { PAYEES } from './_data';
+
+const sizes: NonNullable<ScrollShadowProps['size']>[] = ['small', 'default', 'large'];
+
+const avatarColors: AvatarColor[] = ['brand', 'info', 'success', 'warning', 'danger', 'neutral'];
+
+function Payees() {
+  return PAYEES.map((name, index) => (
+    <VStack key={name} space="xs" className="items-center">
+      <Avatar size="lg" color={avatarColors[index % avatarColors.length]}>
+        <Avatar.Text>{name}</Avatar.Text>
+      </Avatar>
+      <Text size="xs" numberOfLines={1}>
+        {name.split(' ')[0]}
+      </Text>
+    </VStack>
+  ));
+}
+
+export default function ScrollShadowSizesDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-sm">
+      <Card.Header>
+        <Heading size="sm">Send again</Heading>
+      </Card.Header>
+      <Card.Content>
+        {sizes.map((size, index) => (
+          <VStack key={size}>
+            {index > 0 ? <Divider /> : null}
+            <VStack space="sm" className="py-5">
+              <Text size="sm" color="secondary" className="px-5">
+                {size}
+              </Text>
+              <ScrollShadow surface="primary" size={size}>
+                <ScrollView
+                  horizontal
+                  showsHorizontalScrollIndicator={false}
+                  contentContainerClassName="gap-6 px-5"
+                >
+                  <Payees />
+                </ScrollView>
+              </ScrollShadow>
+            </VStack>
+          </VStack>
+        ))}
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Visibility
+
+`visibility` defaults to `auto`, which shows each edge only while content overflows past it. Each fade eases out over its own depth as you scroll toward that edge. `both`, `start`, and `end` force fades on, and `none` hides them. The child can be any single view. Switch modes below and scroll the list to compare.
+
+```tsx
+import { useState } from 'react';
+import {
+  Avatar,
+  Card,
+  Heading,
+  ListItem,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  ToggleButton,
+  VStack,
+  type ScrollShadowProps,
+} from '@cdx-ui/components';
+import { TRANSACTIONS } from './_data';
+
+type Visibility = NonNullable<ScrollShadowProps['visibility']>;
+
+const MODES: Visibility[] = ['auto', 'both', 'start', 'end', 'none'];
+
+export default function ScrollShadowVisibilityDemo() {
+  const [visibility, setVisibility] = useState<Visibility>('both');
+
+  return (
+    <VStack space="md" className="w-full max-w-sm">
+      <ToggleButton.Group
+        type="single"
+        value={visibility}
+        onValueChange={(value) => setVisibility(value as Visibility)}
+        aria-label="visibility"
+      >
+        {MODES.map((mode) => (
+          <ToggleButton key={mode} value={mode} size="small">
+            <ToggleButton.Label>{mode}</ToggleButton.Label>
+          </ToggleButton>
+        ))}
+      </ToggleButton.Group>
+      <Card fullBleed>
+        <Card.Header>
+          <Heading size="sm">Statement · September</Heading>
+        </Card.Header>
+        <Card.Content>
+          <ScrollShadow className="h-64" surface="primary" visibility={visibility}>
+            <ScrollView>
+              {TRANSACTIONS.map((transaction, index) => (
+                <ListItem
+                  key={transaction.id}
+                  size="compact"
+                  showSeparator={index < TRANSACTIONS.length - 1}
+                >
+                  <ListItem.LeadingSlot>
+                    <Avatar color={transaction.isCredit ? 'success' : 'neutral'}>
+                      <Avatar.Icon as={transaction.icon} />
+                    </Avatar>
+                  </ListItem.LeadingSlot>
+                  <ListItem.Content>
+                    <ListItem.Title>{transaction.merchant}</ListItem.Title>
+                  </ListItem.Content>
+                  <ListItem.TrailingSlot>
+                    <Text color={transaction.isCredit ? 'success' : 'primary'}>
+                      {transaction.amount}
+                    </Text>
+                  </ListItem.TrailingSlot>
+                </ListItem>
+              ))}
+            </ScrollView>
+          </ScrollShadow>
+        </Card.Content>
+      </Card>
+    </VStack>
+  );
+}
+```
+
+## Defaults and styling
+
+Start with `surface`, `size`, and `visibility`. If those don't fit, use one of these, from the smallest change to the largest:
+
+- **Different depth or opacity:** pass `edgeClassName`. Its classes go on each fade overlay and are applied after `size`, so they win.
+
+  - Depth: `w-24` makes a horizontal fade 96px deep instead of the `size` value. Use `h-24` for a vertical scroller. Tailwind spacing steps are 4px each, so `w-14` is 56px and `w-24` is 96px.
+  - Opacity: `opacity-85` draws the fade at 85% strength, so a little of the content shows through even at the very edge. Lower values give a softer fade.
+
+  Don't put colors here; a `bg-*` class paints a solid block instead of a fade.
+
+- **Different color:** pass `colorClassName` with an `accent-*` class when the panel isn't one of the `surface` colors, such as a tinted card. It replaces `surface` and still follows dark mode and `ScopedTheme`.
+
+- **Your own indicator:** skip the fade overlays and use `useScrollShadow`. See Hook below.
+
+`hideScrollBar` hides the scrollbar on web only. On iOS and Android, hide it on the child with `showsVerticalScrollIndicator` or `showsHorizontalScrollIndicator`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  Card,
+  Heading,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  ToggleButton,
+  VStack,
+} from '@cdx-ui/components';
+import { ACTIVITY_FILTERS } from './_data';
+
+const OFFERS = [
+  { value: 'groceries', label: '5% back · Groceries' },
+  { value: 'gas', label: '3% back · Gas' },
+  { value: 'streaming', label: '10% back · StreamFlix' },
+  { value: 'dining', label: '2% back · Dining' },
+  { value: 'travel', label: '4% back · Travel' },
+];
+
+function CategoryPicker() {
+  const [category, setCategory] = useState('purchases');
+
+  return (
+    <ToggleButton.Group
+      type="single"
+      isAttached={false}
+      value={category}
+      onValueChange={setCategory}
+      aria-label="Spending category"
+    >
+      {ACTIVITY_FILTERS.map((filter) => (
+        <ToggleButton key={filter.value} value={filter.value} size="small">
+          <ToggleButton.Icon as={filter.icon} position="leading" />
+          <ToggleButton.Label>{filter.label}</ToggleButton.Label>
+        </ToggleButton>
+      ))}
+    </ToggleButton.Group>
+  );
+}
+
+export default function ScrollShadowStylingDemo() {
+  const [activated, setActivated] = useState<string[]>([]);
+
+  return (
+    <VStack space="lg" className="w-full max-w-sm">
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
+          edgeClassName=&quot;w-24&quot;
+        </Text>
+        <Card fullBleed>
+          <Card.Content className="py-5">
+            <ScrollShadow surface="primary" edgeClassName="w-24">
+              <ScrollView
+                horizontal
+                showsHorizontalScrollIndicator={false}
+                contentContainerClassName="px-5"
+              >
+                <CategoryPicker />
+              </ScrollView>
+            </ScrollShadow>
+          </Card.Content>
+        </Card>
+      </VStack>
+
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
+          edgeClassName=&quot;opacity-85&quot;
+        </Text>
+        <Card fullBleed>
+          <Card.Content className="py-5">
+            <ScrollShadow surface="primary" size="small" edgeClassName="opacity-85">
+              <ScrollView
+                horizontal
+                showsHorizontalScrollIndicator={false}
+                contentContainerClassName="px-5"
+              >
+                <CategoryPicker />
+              </ScrollView>
+            </ScrollShadow>
+          </Card.Content>
+        </Card>
+      </VStack>
+
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
+          colorClassName=&quot;accent-surface-action-subtle&quot; hideScrollBar
+        </Text>
+        <Card fullBleed className="bg-surface-action-subtle">
+          <Card.Content fullBleed={false}>
+            <VStack space="xs">
+              <Heading size="xs">Cash back offers</Heading>
+              <Text size="sm" color="secondary">
+                Activate offers, then pay with your Rewards Visa · 1024.
+              </Text>
+            </VStack>
+          </Card.Content>
+          <Box className="pb-5">
+            <ScrollShadow colorClassName="accent-surface-action-subtle" hideScrollBar>
+              <ScrollView
+                horizontal
+                showsHorizontalScrollIndicator={false}
+                contentContainerClassName="px-5"
+              >
+                <ToggleButton.Group
+                  type="multiple"
+                  isAttached={false}
+                  value={activated}
+                  onValueChange={setActivated}
+                  aria-label="Cash back offers"
+                >
+                  {OFFERS.map((offer) => (
+                    <ToggleButton
+                      key={offer.value}
+                      value={offer.value}
+                      variant="outline"
+                      size="small"
+                    >
+                      <ToggleButton.Label>{offer.label}</ToggleButton.Label>
+                    </ToggleButton>
+                  ))}
+                </ToggleButton.Group>
+              </ScrollView>
+            </ScrollShadow>
+          </Box>
+        </Card>
+      </VStack>
+    </VStack>
+  );
+}
+```
+
+## Hook
+
+### useScrollShadow
+
+Use this when you want the overflow state without a fade, for example a "More below" pill or paging chevrons. It does not wrap the scroller and does not paint overlays. Pass the returned handlers onto your `ScrollView` (or `FlatList` / `VirtualizedList`) and read `capability.canScrollBefore` / `canScrollAfter`.
+
+The built-in `ScrollShadow` already uses this hook internally. Exporting it is for custom UI only. You can still wrap the same scroll view in `ScrollShadow` to keep the fades: it keeps your handlers and `ref`, as the paging chevrons below do. Options, return values, and types are on the API tab.
+
+```tsx
+import { useRef } from 'react';
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+import {
+  Box,
+  Card,
+  Heading,
+  HStack,
+  IconButton,
+  ScrollShadow,
+  ScrollView,
+  Text,
+  VStack,
+  useScrollShadow,
+} from '@cdx-ui/components';
+import { ChevronLeft, ChevronRight } from '@cdx-ui/icons';
+import { ACCOUNTS } from './_data';
+
+export default function ScrollShadowHookDemo() {
+  const scrollRef = useRef<ScrollView>(null);
+  const offset = useRef(0);
+  const viewport = useRef(0);
+  const { capability, handleLayout, handleContentSizeChange, handleScroll } = useScrollShadow({
+    orientation: 'horizontal',
+  });
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    viewport.current = event.nativeEvent.layout.width;
+    handleLayout(event);
+  };
+
+  const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    offset.current = event.nativeEvent.contentOffset.x;
+    handleScroll(event);
+  };
+
+  const page = (direction: -1 | 1) => {
+    const x = Math.max(0, offset.current + direction * viewport.current * 0.8);
+    scrollRef.current?.scrollTo({ x, animated: true });
+  };
+
+  return (
+    <Card fullBleed className="w-full max-w-sm">
+      <Card.Header>
+        <Heading size="sm">Your accounts</Heading>
+        <HStack space="xs">
+          <IconButton
+            as={ChevronLeft}
+            variant="subtle"
+            size="small"
+            isDisabled={!capability.canScrollBefore}
+            onPress={() => page(-1)}
+            accessibilityLabel="Previous accounts"
+          />
+          <IconButton
+            as={ChevronRight}
+            variant="subtle"
+            size="small"
+            isDisabled={!capability.canScrollAfter}
+            onPress={() => page(1)}
+            accessibilityLabel="Next accounts"
+          />
+        </HStack>
+      </Card.Header>
+      <Card.Content>
+        <Box className="py-5">
+          <ScrollShadow surface="primary">
+            <ScrollView
+              ref={scrollRef}
+              horizontal
+              contentContainerClassName="gap-3 px-5"
+              onContentSizeChange={handleContentSizeChange}
+              onLayout={onLayout}
+              onScroll={onScroll}
+              scrollEventThrottle={16}
+              showsHorizontalScrollIndicator={false}
+            >
+              {ACCOUNTS.map((account) => (
+                <Card key={account.mask} className="w-52">
+                  <Card.Stripe />
+                  <Card.Content>
+                    <VStack space="xs">
+                      <Text size="sm" color="secondary">
+                        {account.name} · {account.mask}
+                      </Text>
+                      <Heading size="md">{account.balance}</Heading>
+                      <Text size="xs" color="tertiary">
+                        {account.label}
+                      </Text>
+                    </VStack>
+                  </Card.Content>
+                </Card>
+              ))}
+            </ScrollView>
+          </ScrollShadow>
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## API
+
+### ScrollShadow
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | — | The scroll view to decorate: a `ScrollView`, `FlatList`, or `VirtualizedList`, passed as the direct child. With a forced `visibility`, any single view works. |
+| `className?` | `string` | — | Classes for the wrapping view, for example `h-full` or `flex-1` to bound the scroller. |
+| `style?` | `StyleProp<ViewStyle>` | — | Style for the wrapping view. |
+| `orientation?` | `'horizontal' \| 'vertical'` | `inferred from the child's `horizontal` prop, otherwise `'vertical'`` | Scroll axis that gets fades. |
+| `surface?` | `'background' \| 'primary' \| 'secondary'` | `'background'` | Theme surface the fade blends into. Match it to the background behind the scroller. |
+| `size?` | `'small' \| 'default' \| 'large'` | `'default'` | Fade depth along the scroll axis: `small` is 32px, `default` is 40px, `large` is 72px. |
+| `visibility?` | `'auto' \| 'both' \| 'start' \| 'end' \| 'none'` | `'auto'` | Which edges show a fade. `auto` follows the scroll position; `both`, `start`, and `end` force those edges on; `none` hides them. |
+| `offset?` | `number` | `0` | Pixels of scroll slack before an edge counts as scrollable. Only used with `auto`. |
+| `hideScrollBar?` | `boolean` | `false` | Hides the child's scrollbar on web. On iOS and Android, set `showsVerticalScrollIndicator` or `showsHorizontalScrollIndicator` on the child instead. |
+| `edgeClassName?` | `string` | — | 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. |
+| `colorClassName?` | `string` | — | One-off fade color outside the `surface` options, as an `accent-*` class. Overrides `surface` on every platform and follows dark mode and `ScopedTheme`. |
+| `onCapabilityChange?` | `((capability: ScrollShadowCapability) => void)` | — | Called when either edge starts or stops being scrollable, with `{ canScrollBefore, canScrollAfter }`. Only fires with `visibility="auto"`. |
+
+Does not extend a React Native base component. Every prop is listed above. `ScrollShadow` keeps the child's own `onScroll`, `onLayout`, and `onContentSizeChange` handlers, including a Reanimated scroll handler, and sets `scrollEventThrottle={16}` when the child doesn't set one.
+
+| Attribute   | Values           | Description                  |
+| ----------- | ---------------- | ---------------------------- |
+| `data-edge` | `start` \| `end` | Which edge an overlay covers |
+
+## Hook
+
+### useScrollShadow
+
+Tracks whether a scroller can scroll toward its start or end, without rendering any overlay. Spread the handlers onto your scroll view and draw your own indicator from `capability`:
+
+```tsx
+const { capability, handleLayout, handleContentSizeChange, handleScroll } = useScrollShadow({
+  orientation: 'vertical',
+});
+```
+
+| Option               | Type                                           | Description                                         |
+| -------------------- | ---------------------------------------------- | --------------------------------------------------- |
+| `orientation`        | `'horizontal' \| 'vertical'`                   | Scroll axis to track. Defaults to `vertical`        |
+| `offset`             | `number`                                       | Pixels of slack before an edge counts as scrollable |
+| `enabled`            | `boolean`                                      | Stops tracking when `false`                         |
+| `onCapabilityChange` | `(capability: ScrollShadowCapability) => void` | Called when either edge flips                       |
+
+| Return                    | Type                                                       | Description                          |
+| ------------------------- | ---------------------------------------------------------- | ------------------------------------ |
+| `capability`              | `{ canScrollBefore: boolean; canScrollAfter: boolean }`    | Whether content overflows each edge  |
+| `handleLayout`            | `(event: LayoutChangeEvent) => void`                       | Pass to the scroll view's `onLayout` |
+| `handleContentSizeChange` | `(width: number, height: number) => void`                  | Pass to `onContentSizeChange`        |
+| `handleScroll`            | `(event: NativeSyntheticEvent<NativeScrollEvent>) => void` | Pass to `onScroll`                   |
+
+## Anatomy
+
+| `data-slot`          | Element                          |
+| -------------------- | -------------------------------- |
+| `scroll-shadow`      | Root wrapper around the scroller |
+| `scroll-shadow-edge` | Start or end fade overlay        |
+
+## Accessibility
+
+The fade overlays are decorative. They pass touches through to the scroller and are hidden from screen readers with `aria-hidden`, `accessibilityElementsHidden`, and `importantForAccessibility="no-hide-descendants"`. The scrollable content stays fully reachable, so a fade never hides content from assistive technology.