### Development Setup for Use Scroll Fades

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Instructions for setting up the development environment for the use-scroll-fades project. This includes installing dependencies, running tests, and building the project.

```bash
# Development setup
npm install
npm run test
npm run build
```

--------------------------------

### Install @gboue/use-scroll-fades with npm, yarn, or pnpm

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

This snippet shows how to install the use-scroll-fades package using common JavaScript package managers: npm, yarn, and pnpm. These commands are executed in the terminal.

```bash
# npm
npm i @gboue/use-scroll-fades
# or
yarn add @gboue/use-scroll-fades
# or
pnpm add @gboue/use-scroll-fades
```

--------------------------------

### Integrate useScrollFades with react-window for Virtualized Lists

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

This example shows how to use the `useScrollFades` hook with `react-window` to create a performant virtualized list. It ensures smooth fade effects on scrollable containers, even with a large number of items. The hook manages the container reference and styling for fade effects.

```tsx
import { FixedSizeList as List } from 'react-window'
import { useScrollFades } from '@gboue/use-scroll-fades'

function VirtualizedScrollList({ items }) {
  const { containerRef, state, getContainerStyle } = useScrollFades({
    threshold: 8,
    fadeSize: 20
  })

  const Row = ({ index, style }) => (
    <div style={{ ...style, padding: '8px 16px', borderBottom: '1px solid #eee' }}>
      <strong>{items[index].title}</strong>
      <p style={{ margin: '4px 0', color: '#666' }}>{items[index].subtitle}</p>
    </div>
  )

  return (
    <div style={{ position: 'relative', height: 500, width: 400 }}>
      <div
        ref={containerRef}
        style={{
          height: '100%',
          width: '100%',
          overflow: 'auto',
          ...getContainerStyle()
        }}
      >
        <List
          height={500}
          itemCount={items.length}
          itemSize={60}
          width={400}
          outerElementType={React.forwardRef((props, ref) => (
            <div {...props} ref={ref} />
          ))}
        >
          {Row}
        </List>
      </div>
    </div>
  )
}

// Usage with large dataset
const largeDataset = Array.from({ length: 10000 }, (_, i) => ({
  id: i,
  title: `Item ${i + 1}`,
  subtitle: `Subtitle for item ${i + 1}`
}))

<VirtualizedScrollList items={largeDataset} />
// Efficient rendering with fade indicators
// Works with 10,000+ items without performance issues
```

--------------------------------

### Image/Pattern Background with Mask-Image

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Illustrates using the mask-image approach for scroll fade effects on a container with an image or pattern background. This example showcases the 'true transparency' benefit, allowing the background pattern to show through the fades perfectly. It uses React hooks and inline styles.

```tsx
import React, { useRef } from 'react';

// Assume getContainerStyle is defined elsewhere and returns the necessary styles for mask-image
const getContainerStyle = () => ({
  WebkitMaskImage: 'linear-gradient(to right, transparent, black 50%, transparent)',
  maskImage: 'linear-gradient(to right, transparent, black 50%, transparent)'
});

const ImagePatternExample = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  return (
    <div 
      ref={containerRef}
      style={{
        overflow: 'auto',
        backgroundImage: 'url("your-pattern.svg")',
        backgroundColor: '#f8fafc',
        ...getContainerStyle() // ✅ True transparency shows the pattern perfectly!
      }}
    >
      {/* Your content */}
      <p>Content with pattern background...</p>
      <div style={{ height: '800px' }}></div>
    </div>
  );
};

export default ImagePatternExample;
```

--------------------------------

### Scroll Fade with React Window Virtualized Lists

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

This example demonstrates integrating the use-scroll-fades hook with React Window for virtualized lists. It shows how to pass the `containerRef` from the hook to the `List` component and utilize `getOverlayStyle` to apply dynamic styles for fade overlays. This approach is efficient for rendering large lists while maintaining scroll fade effects.

```tsx
import React from 'react'
import { FixedSizeList as List } from 'react-window'
import { useScrollFades } from '@gboue/use-scroll-fades'

export default function VirtualizedList({ items }) {
  const { containerRef, state, getOverlayStyle } = useScrollFades()

  return (
    <div style={{ position: 'relative', height: 400, width: 300 }}>
      <List
        ref={containerRef}
        height={400}
        itemCount={items.length}
        itemSize={50}
      >
        {({ index, style }) => (
          <div style={style}>
            {items[index]}
          </div>
        )}
      </List>
      
      <div aria-hidden style={{ 
        ...getOverlayStyle('top', state),
        position: 'absolute', top: 0, left: 0, right: 0, height: 30
      }} />
      <div aria-hidden style={{ 
        ...getOverlayStyle('bottom', state),
        position: 'absolute', bottom: 0, left: 0, right: 0, height: 30
      }} />
    </div>
  )
}

```

--------------------------------

### Legacy Overlay Approach for Scroll Fades (TSX - Deprecated)

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Utilize a deprecated overlay method for backward compatibility with scroll fade effects. This TSX example uses the useScrollFades hook to get the container reference and overlay styles. It's designed for solid backgrounds and provides absolute positioning for top and bottom overlays, though it's recommended to use the mask-image approach for better results.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function LegacyScrollableList({ items }) {
  const { containerRef, state, getOverlayStyle } = useScrollFades({
    threshold: 16,
    transitionDuration: 300
  })

  return (
    <div style={{ position: 'relative' }}>
      <div 
        ref={containerRef}
        style={{ height: '400px', overflow: 'auto' }}
      >
        {items.map(item => (
          <div key={item.id}>{item.name}</div>
        ))}
      </div>
      
      {/* Overlay elements - only work well on solid backgrounds */}
      <div 
        style={{
          position: 'absolute',
          top: 0,
          left: 0,
          right: 0,
          height: '20px',
          ...getOverlayStyle('top')
        }}
      />
      <div 
        style={{
          position: 'absolute',
          bottom: 0,
          left: 0,
          right: 0,
          height: '20px',
          ...getOverlayStyle('bottom')
        }}
      />
    </div>
  )
}
```

--------------------------------

### Configure Custom Scroll Fade Animations with useScrollFades

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

This example demonstrates how to customize the scroll fade animations using the `useScrollFades` hook by adjusting `transitionDuration` and `transitionTimingFunction`. It showcases different animation styles like fast, smooth, bouncy, and instant (no animation). Each configuration targets a separate scrollable div.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function CustomAnimatedList({ items }) {
  // Fast, snappy animations
  const fast = useScrollFades({
    transitionDuration: 100,
    transitionTimingFunction: 'linear'
  })

  // Smooth, material design animations
  const smooth = useScrollFades({
    transitionDuration: 300,
    transitionTimingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)'
  })

  // Bouncy effect
  const bouncy = useScrollFades({
    transitionDuration: 500,
    transitionTimingFunction: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
  })

  // No animations (instant)
  const instant = useScrollFades({
    disableTransitions: true
  })

  return (
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 1fr)', gap: '16px' }}>
      <div>
        <h3>Fast (100ms linear)</h3>
        <div
          ref={fast.containerRef}
          style={{ height: '200px', overflow: 'auto', ...fast.getContainerStyle() }}
        >
          {items.map(item => <div key={item.id}>{item.name}</div>)}
        </div>
      </div>

      <div>
        <h3>Smooth (300ms material)</h3>
        <div
          ref={smooth.containerRef}
          style={{ height: '200px', overflow: 'auto', ...smooth.getContainerStyle() }}
        >
          {items.map(item => <div key={item.id}>{item.name}</div>)}
        </div>
      </div>

      <div>
        <h3>Bouncy (500ms bounce)</h3>
        <div
          ref={bouncy.containerRef}
          style={{ height: '200px', overflow: 'auto', ...bouncy.getContainerStyle() }}
        >
          {items.map(item => <div key={item.id}>{item.name}</div>)}
        </div>
      </div>

      <div>
        <h3>Instant (no animation)</h3>
        <div
          ref={instant.containerRef}
          style={{ height: '200px', overflow: 'auto', ...instant.getContainerStyle() }}
        >
          {items.map(item => <div key={item.id}>{item.name}</div>)}
        </div>
      </div>
    </div>
  )
}

<CustomAnimatedList items={items} />
// Compare different animation styles side by side

```

--------------------------------

### Styled Components Integration with useScrollFades

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

Illustrates seamless integration of the use-scroll-fades hook with styled-components for creating scrollable lists with fade effects. It shows how to apply inline styles returned by getContainerStyle() to styled components, merging them with existing styles. This example highlights customizable fade effects and transitions.

```tsx
import styled from 'styled-components'
import { useScrollFades } from '@gboue/use-scroll-fades'

const ScrollContainer = styled.div`
  overflow: auto;
  height: 400px;
  background: white;
  border-radius: 12px;
  padding: 16px;
`

const ListItem = styled.div`
  padding: 16px;
  margin: 8px 0;
  background: #f8f9fa;
  border-radius: 8px;
  transition: background 0.2s;

  &:hover {
    background: #e9ecef;
  }
`

function StyledScrollList({ items }) {
  const { containerRef, getContainerStyle, state } = useScrollFades({
    threshold: 10,
    fadeSize: 24,
    transitionDuration: 250
  })

  return (
    <ScrollContainer
      ref={containerRef}
      style={getContainerStyle()}
    >
      {items.map(item => (
        <ListItem key={item.id}>
          <h3>{item.title}</h3>
          <p>{item.description}</p>
        </ListItem>
      ))}
    </ScrollContainer>
  )
}

// Usage
const items = [
  { id: 1, title: 'First Item', description: 'Description for first item' },
  { id: 2, title: 'Second Item', description: 'Description for second item' },
  { id: 3, title: 'Third Item', description: 'Description for third item' }
]

<StyledScrollList items={items} />
// Combines styled-components with scroll fade effects
// getContainerStyle() returns inline styles that merge with styled-components

```

--------------------------------

### Advanced Custom Color Fade Overlay Method (TSX)

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Implement advanced scroll fade effects using an overlay method for full control over positioning and appearance. This example utilizes the useScrollFades hook to manage scroll state and a useRef hook to position custom gradient overlays. It requires React and the useScrollFades hook, outputting a container with dynamically positioned fade overlays.

```tsx
import React, { useRef, useEffect } from 'react';
import { useScrollFades } from '@gboue/use-scroll-fades';

function AdvancedColorFadeList({ items }) {
  const { containerRef, state } = useScrollFades({
    threshold: 8,
    fadeSize: 50,
    transitionDuration: 300
  });

  const topFadeRef = useRef(null);
  const bottomFadeRef = useRef(null);

  // Custom colors with opacity
  const topColor = 'rgba(255, 69, 0, 0.2)';    // Orange fade
  const bottomColor = 'rgba(0, 128, 255, 0.2)'; // Blue fade

  // Position overlays to match container
  useEffect(() => {
    const updatePositions = () => {
      if (!containerRef.current) return;
      
      const rect = containerRef.current.getBoundingClientRect();
      const style = window.getComputedStyle(containerRef.current);
      
      if (topFadeRef.current) {
        topFadeRef.current.style.top = `${rect.top}px`;
        topFadeRef.current.style.left = `${rect.left}px`;
        topFadeRef.current.style.width = `${rect.width}px`;
        topFadeRef.current.style.borderRadius = style.borderRadius;
      }
      
      if (bottomFadeRef.current) {
        bottomFadeRef.current.style.bottom = `${window.innerHeight - rect.bottom}px`;
        bottomFadeRef.current.style.left = `${rect.left}px`;
        bottomFadeRef.current.style.width = `${rect.width}px`;
        bottomFadeRef.current.style.borderRadius = style.borderRadius;
      }
    };

    updatePositions();
    const interval = setInterval(updatePositions, 100);
    
    return () => clearInterval(interval);
  }, []);

  return (
    <div style={{ position: 'relative' }}>
      <div 
        ref={containerRef}
        style={{
          height: '400px',
          overflow: 'auto',
          background: '#ffffff',
          borderRadius: '16px',
          border: '1px solid #e2e8f0'
        }}
      >
        {items.map(item => (
          <div key={item.id} style={{ padding: '1rem', margin: '1rem' }}>
            {item.content}
          </div>
        ))}
      </div>

      {/* Colored fade overlays */}
      <div 
        ref={topFadeRef}
        style={{
          position: 'fixed',
          height: '50px',
          background: `linear-gradient(to bottom, ${topColor}, transparent)`,
          display: state.showTop ? 'block' : 'none',
          pointerEvents: 'none',
          zIndex: 10
        }}
      />
      <div 
        ref={bottomFadeRef}
        style={{
          position: 'fixed',
          height: '50px',
          background: `linear-gradient(to top, ${bottomColor}, transparent)`,
          display: state.showBottom ? 'block' : 'none',
          pointerEvents: 'none',
          zIndex: 10
        }}
      />
    </div>
  );
}
```

--------------------------------

### Combined Vertical and Horizontal Scrolling with useScrollFades (React)

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

Illustrates using useScrollFades for containers with both vertical and horizontal scrolling. The hook automatically detects and applies all four fade directions (top, bottom, left, right) based on the scroll state. It requires similar setup with 'containerRef' and 'getContainerStyle'.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function DataGrid({ data }) {
  const { containerRef, getContainerStyle, state } = useScrollFades({
    threshold: 8,
    fadeSize: 20
  })

  return (
    <div
      ref={containerRef}
      style={{
        width: '600px',
        height: '400px',
        overflow: 'auto',
        ...getContainerStyle()
      }}
    >
      <table style={{ minWidth: '1200px', borderCollapse: 'collapse' }}>
        <thead>
          <tr>
            <th style={{ padding: '12px', background: '#f8f9fa' }}>Column 1</th>
            <th style={{ padding: '12px', background: '#f8f9fa' }}>Column 2</th>
            <th style={{ padding: '12px', background: '#f8f9fa' }}>Column 3</th>
            <th style={{ padding: '12px', background: '#f8f9fa' }}>Column 4</th>
          </tr>
        </thead>
        <tbody>
          {data.map((row, i) => (
            <tr key={i}>
              <td style={{ padding: '12px', border: '1px solid #dee2e6' }}>{row.col1}</td>
              <td style={{ padding: '12px', border: '1px solid #dee2e6' }}>{row.col2}</td>
              <td style={{ padding: '12px', border: '1px solid #dee2e6' }}>{row.col3}</td>
              <td style={{ padding: '12px', border: '1px solid #dee2e6' }}>{row.col4}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  )
}

// Usage
const data = Array.from({ length: 50 }, (_, i) => ({
  col1: `A${i}`,
  col2: `B${i}`,
  col3: `C${i}`,
  col4: `D${i}`
}))

<DataGrid data={data} />
// Shows all four fade indicators (top, bottom, left, right)
// state.showTop, state.showBottom, state.showLeft, state.showRight
```

--------------------------------

### Apply Custom Colors to Scroll Fade Effects

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

This example demonstrates how to apply custom colors to the fade effects for branding. You can set a single `fadeColor` or define `topColors`, `bottomColors`, `leftColors`, and `rightColors` for directional gradients. Use `getColoredFadeClass()` to enable colored fade support and `getGradientProperties()` to apply the custom gradients to the container's style.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function ColoredScrollableList({ items }) {
  const {
    containerRef,
    getContainerStyle,
    getGradientProperties,
    getColoredFadeClass,
    state
  } = useScrollFades({
    fadeColor: 'rgba(0, 122, 255, 0.3)', // Single color for all fades
    threshold: 16,
    fadeSize: 24
  })

  return (
    <div
      ref={containerRef}
      className={getColoredFadeClass()} // Enable colored fade support
      style={{
        height: '400px',
        overflow: 'auto',
        background: 'linear-gradient(135deg, #667eea, #764ba2)',
        ...getContainerStyle(),
        ...getGradientProperties() // Apply colored gradients
      }}
    >
      {items.map(item => (
        <div key={item.id} style={{ padding: '16px' }}>
          {item.name}
        </div>
      ))}
    </div>
  )
}

// Usage with different colors per direction
function MultiColorFadeList({ items }) {
  const {
    containerRef,
    getContainerStyle,
    getGradientProperties,
    getColoredFadeClass
  } = useScrollFades({
    topColors: { from: 'rgba(255, 0, 0, 0.4)', to: 'transparent' },
    bottomColors: { from: 'rgba(0, 255, 0, 0.4)', to: 'transparent' },
    leftColors: { from: 'rgba(0, 0, 255, 0.4)', to: 'transparent' },
    rightColors: { from: 'rgba(255, 255, 0, 0.4)', to: 'transparent' }
  })

  return (
    <div
      ref={containerRef}
      className={getColoredFadeClass()}
      style={{
        height: '400px',
        width: '500px',
        overflow: 'auto',
        ...getContainerStyle(),
        ...getGradientProperties()
      }}
    >
      <div style={{ width: '1000px', height: '800px' }}>
        Wide and tall content with colored fades on all edges
      </div>
    </div>
  )
}

<ColoredScrollableList items={items} />
// Renders with blue-tinted fade effects matching brand color
```

--------------------------------

### Apply Custom CSS Classes for Scroll Fade Styling

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Demonstrates advanced usage of `useScrollFades` by integrating with custom CSS classes for styling scroll fade effects. Instead of relying solely on inline styles, this example applies specific CSS classes (`scroll-container`, `scrollable-content`, `list-item`, `fade-overlay`, `visible`, `hidden`) to elements, allowing for more maintainable and themeable styles. It also shows how to conditionally apply classes based on the hook's state.

```tsx
import React from 'react'
import { useScrollFades } from '@gboue/use-scroll-fades'
import './ScrollFades.css' // Your custom CSS

export default function CustomStyledList({ items }) {
  const { containerRef, state } = useScrollFades({ threshold: 16 })

  return (
    <div className="scroll-container">
      <div ref={containerRef} className="scrollable-content">
        {items.map((item, i) => (
          <div key={i} className="list-item">{item}</div>
        ))}
      </div>
      
      {/* Custom CSS classes instead of inline styles */}
      <div className={`fade-overlay fade-top ${state.showTop ? 'visible' : 'hidden'}`} />
      <div className={`fade-overlay fade-bottom ${state.showBottom ? 'visible' : 'hidden'}`} />
    </div>
  )
}
```

--------------------------------

### Individual Direction Colors with useScrollFades (TSX)

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Apply distinct gradient fade colors to the top, bottom, left, and right edges of a scrollable container. This example uses the useScrollFades hook to manage the container reference and styling, accepting custom color objects for each direction. It outputs a styled container with directional fades.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function CustomGradientList({ items }) {
  const { 
    containerRef, 
    getContainerStyle,
    getGradientProperties,
    getColoredFadeClass
  } = useScrollFades({
    topColors: { from: 'rgba(255, 0, 0, 0.4)', to: 'transparent' },
    bottomColors: { from: 'rgba(0, 255, 0, 0.4)', to: 'transparent' },
    leftColors: { from: 'rgba(0, 0, 255, 0.4)', to: 'transparent' },
    rightColors: { from: 'rgba(255, 255, 0, 0.4)', to: 'transparent' }
  })

  return (
    <div 
      ref={containerRef}
      className={getColoredFadeClass()}
      style={{
        height: '400px',
        overflow: 'auto',
        ...getContainerStyle(),
        ...getGradientProperties()
      }}
    >
      {items.map(item => <div key={item.id}>{item.name}</div>)}
    </div>
  )
}
```

--------------------------------

### CSS Transitions for Scroll Fade Animations

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

This CSS snippet illustrates the use of `opacity` transitions with vendor prefixes for implementing smooth scroll fade animations. It is designed for maximum browser compatibility, including `-webkit-` for Safari, `-moz-` for Firefox, and `-ms-` for Internet Explorer/Edge. This approach leverages GPU acceleration for performance.

```css
transition: opacity 200ms ease-out;
-webkit-transition: opacity 200ms ease-out; /* Safari */
-moz-transition: opacity 200ms ease-out;    /* Firefox */
-ms-transition: opacity 200ms ease-out;     /* IE/Edge */
```

--------------------------------

### Migrate React Scroll Fades: Overlay to Mask-Image Approach

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Demonstrates the migration from the older overlay-based fading technique to the newer mask-image approach in React. This involves changing how styles are applied to achieve the fading effect, moving from absolute positioning for overlays to applying styles directly to the container.

```tsx
// OLD overlay approach ❌
<div style={{ position: 'relative' }}>
  <div ref={containerRef} style={{ overflow: 'auto' }}>
    {content}
  </div>
  <div style={{ position: 'absolute', top: 0, ...getOverlayStyle('top') }} />
  <div style={{ position: 'absolute', bottom: 0, ...getOverlayStyle('bottom') }} />
</div>

// NEW mask-image approach ✅  
<div ref={containerRef} style={{ overflow: 'auto', ...getContainerStyle() }}>
  {content}
</div>
```

--------------------------------

### Configure Scroll Fade Animations with useScrollFades Options

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Illustrates various ways to configure the `useScrollFades` hook for different animation behaviors. This includes setting custom transition durations and timing functions, achieving faster animations, disabling transitions entirely for instant effects, and applying advanced CSS timing functions like cubic-bezier for custom easing.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

// Default smooth animations (200ms ease-out)
const { containerRef, state, getOverlayStyle } = useScrollFades()

// Custom animation timing
const customAnimated = useScrollFades({
  transitionDuration: 300, // 300ms duration
  transitionTimingFunction: 'ease-in-out' // Custom easing
})

// Faster animations
const quickFades = useScrollFades({
  transitionDuration: 100, // Snappy 100ms
  transitionTimingFunction: 'ease-out'
})

// Disable animations entirely
const noAnimations = useScrollFades({
  disableTransitions: true // Instant show/hide
})

// Custom CSS transitions (for advanced users)
const advancedAnimations = useScrollFades({
  transitionTimingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)' // Material Design easing
})
```

--------------------------------

### TypeScript: useScrollFades Hook Signature and Return Types

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Defines the signature and return types for the useScrollFades React hook. It returns a container reference, the current fade state, and several utility functions for applying styles and retrieving accessibility information.

```typescript
export function useScrollFades<T extends HTMLElement = HTMLElement>(
  options?: UseScrollFadesOptions
): {
  containerRef: React.RefObject<T>,
  state: FadeState,
  getContainerStyle: (state?: FadeState) => React.CSSProperties,
  getOverlayStyle: (
    position: 'top' | 'bottom' | 'left' | 'right',
    state?: FadeState
  ) => React.CSSProperties,
  getGradientProperties: (state?: FadeState) => Record<string, string>,
  getColoredFadeClass: () => string,
  accessibility: {
    shouldApplyEffects: boolean,
    reducedMotionPreferred: boolean,
    browserCapabilities: object,
    shouldDisableTransitions: boolean
  }
}
```

--------------------------------

### Manual Browser Feature Detection with useScrollFades Utilities

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Shows how to manually check for browser capabilities relevant to scroll fades. It utilizes `supportsMaskImage` to detect if the browser supports CSS mask-image and `prefersReducedMotion` to check the user's preference for reduced motion. This allows for proactive adjustments or conditional logic before applying effects.

```tsx
import { supportsMaskImage, prefersReducedMotion } from '@gboue/use-scroll-fades'

// Check browser capabilities manually
if (supportsMaskImage()) {
  console.log('Mask-image is supported!')
}

if (prefersReducedMotion()) {
  console.log('User prefers reduced motion')
}
```

--------------------------------

### Implement Accessible Scroll List with useScrollFades

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Demonstrates how to use the useScrollFades hook to create a scrollable list with accessibility features. It automatically respects user preferences for reduced motion and checks browser support for CSS mask-image, falling back gracefully when needed. The hook provides access to detailed accessibility information via the `accessibility` object.

```tsx
function AccessibleScrollList() {
  const { containerRef, getContainerStyle, accessibility } = useScrollFades({
    respectReducedMotion: true,      // Default: true - respects user preference
    respectBrowserSupport: true,     // Default: true - checks browser capabilities  
    maskImageFallback: 'disable'    // Default: 'disable' - what to do if unsupported
  })
  
  // Access detailed accessibility information
  console.log(accessibility.shouldApplyEffects)      // false if user prefers reduced motion
  console.log(accessibility.reducedMotionPreferred)  // current user preference
  console.log(accessibility.browserCapabilities)     // detailed browser info
  console.log(accessibility.shouldDisableTransitions) // whether transitions are disabled

  return (
    <div 
      ref={containerRef}
      style={{
        height: '300px',
        overflow: 'auto',
        ...getContainerStyle()  // Will be empty if effects should not apply
      }}
    >
      {/* Your content */}
    </div>
  )
}
```

--------------------------------

### TypeScript: Define Scroll Fade States and Options

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Defines the TypeScript types for fade visibility states (top, bottom, left, right) and configuration options for the useScrollFades hook. This includes gradient color definitions, fade sizes, transition properties, and accessibility settings.

```typescript
export type FadeState = {
  showTop: boolean,
  showBottom: boolean,
  showLeft: boolean,
  showRight: boolean
}

export type GradientColors = {
  from: string,
  to: string
}

export type UseScrollFadesOptions = {
  threshold?: number,
  fadeSize?: number,
  fadeColor?: string,
  topColors?: GradientColors,
  bottomColors?: GradientColors,
  leftColors?: GradientColors,
  rightColors?: GradientColors,
  topGradient?: string,
  bottomGradient?: string,
  leftGradient?: string,
  rightGradient?: string,
  transitionDuration?: number,
  transitionTimingFunction?: string,
  disableTransitions?: boolean,
  respectReducedMotion?: boolean,
  respectBrowserSupport?: boolean,
  maskImageFallback?: 'disable' | 'ignore'
}
```

--------------------------------

### Accessibility Utilities with useScrollFades

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

Demonstrates how to use use-scroll-fades to respect user preferences for reduced motion and check browser capabilities. It integrates with React hooks to manage motion preference state and logs detailed browser capabilities. Outputs include whether effects should apply, if reduced motion is preferred, browser capabilities, and if transitions should be disabled.

```tsx
import {
  prefersReducedMotion,
  supportsMaskImage,
  getBrowserCapabilities,
  watchMotionPreference
} from '@gboue/use-scroll-fades'

function AccessibleScroller({ items }) {
  const [motionPreferred, setMotionPreferred] = React.useState(false)

  React.useEffect(() => {
    // Check initial preference
    setMotionPreferred(prefersReducedMotion())

    // Watch for changes
    const cleanup = watchMotionPreference((prefersReduced) => {
      setMotionPreferred(prefersReduced)
      console.log('Motion preference changed:', prefersReduced)
    })

    return cleanup
  }, [])

  // Get comprehensive browser capabilities
  const capabilities = getBrowserCapabilities()
  console.log(capabilities)
  // Output: {
  //   prefersReducedMotion: false,
  //   prefersHighContrast: false,
  //   motionPreference: 'no-preference',
  //   supportsMaskImage: true,
  //   supportsTransitions: true,
  //   isSSR: false,
  //   hasMatchMedia: true,
  //   hasCSSSupports: true
  // }

  const { containerRef, getContainerStyle, accessibility } = useScrollFades({
    respectReducedMotion: true,
    respectBrowserSupport: true
  })

  // Access accessibility info from hook
  console.log(accessibility.shouldApplyEffects)      // false if reduced motion
  console.log(accessibility.reducedMotionPreferred)  // user preference
  console.log(accessibility.browserCapabilities)     // detailed capabilities
  console.log(accessibility.shouldDisableTransitions) // whether to disable animations

  return (
    <div
      ref={containerRef}
      style={{
        height: '400px',
        overflow: 'auto',
        ...getContainerStyle()
      }}
    >
      {supportsMaskImage() ? (
        <p>✓ Mask-image supported - full fade effects enabled</p>
      ) : (
        <p>⚠ Mask-image not supported - effects disabled</p>
      )}
      {items.map(item => <div key={item.id}>{item.name}</div>)}
    </div>
  )
}

<AccessibleScroller items={items} />
// Automatically respects user preferences
// Disables effects if browser doesn't support mask-image

```

--------------------------------

### Complex Gradient Background with Mask-Image

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Demonstrates applying scroll fade effects to a container with a complex gradient background using the recommended mask-image approach. This method ensures true transparency and works seamlessly with various background types. It utilizes React's `useRef` and a hypothetical `getContainerStyle` function to apply the necessary styles.

```tsx
import React, { useRef } from 'react';

// Assume getContainerStyle is defined elsewhere and returns the necessary styles for mask-image
const getContainerStyle = () => ({
  WebkitMaskImage: 'linear-gradient(to right, transparent, black 50%, transparent)',
  maskImage: 'linear-gradient(to right, transparent, black 50%, transparent)'
});

const ComplexGradientExample = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  return (
    <div 
      ref={containerRef}
      style={{
        height: '400px',
        overflow: 'auto',
        backgroundImage: 'linear-gradient(135deg, #667eea 0%, #764ba2 50%, #f093fb 100%)',
        ...getContainerStyle() // ✅ Perfect transparency with mask-image!
      }}
    >
      {/* Your scrollable content */}
      <p>Scrollable content here...</p>
      <div style={{ height: '800px' }}></div>
    </div>
  );
};

export default ComplexGradientExample;
```

--------------------------------

### Implement Scroll Fade Indicators with useScrollFades Hook

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

This hook manages scroll-fade state and provides styling functions for scrollable containers. It takes configuration options like threshold, fadeSize, and transition durations. The `containerRef` should be attached to the scrollable element, and `getContainerStyle()` applies the fade mask. The `state` object reflects the current scroll position relative to edges.

```tsx
import { useScrollFades } from '@gboue/use-scroll-fades'

function ScrollableList({ items }) {
  const { containerRef, getContainerStyle, state } = useScrollFades({
    threshold: 16,        // Distance from edge before fades appear (px)
    fadeSize: 20,         // Size of fade effect (px)
    transitionDuration: 300, // Animation duration (ms)
    transitionTimingFunction: 'ease-out',
    disableTransitions: false,
    respectReducedMotion: true,
    respectBrowserSupport: true,
    maskImageFallback: 'disable'
  })

  return (
    <div
      ref={containerRef}
      style={{
        height: '400px',
        overflow: 'auto',
        background: 'linear-gradient(135deg, #667eea, #764ba2)',
        ...getContainerStyle() // Apply fade mask
      }}
    >
      {items.map(item => (
        <div key={item.id} style={{ padding: '16px' }}>
          {item.name}
        </div>
      ))}
    </div>
  )
}

// Usage
const items = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' },
  { id: 3, name: 'Item 3' },
  { id: 4, name: 'Item 4' },
  { id: 5, name: 'Item 5' }
]

<ScrollableList items={items} />
// Renders a scrollable list with top/bottom fade indicators
// State updates automatically as user scrolls
```

--------------------------------

### Generate Gradient Fade CSS Properties and Stylesheet - TypeScript

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

Demonstrates how to use `generateFadeGradientProperties` to create CSS custom properties for gradient fades and `generateColoredFadeCSS` to generate a CSS stylesheet. This is useful for customizing scroll fade appearances.

```tsx
import {
  generateFadeGradientProperties,
  generateColoredFadeCSS,
  COLORED_FADE_CLASS,
  DEFAULT_GRADIENT_COLORS
} from '@gboue/use-scroll-fades'

// Generate CSS custom properties for colored fades
const gradientProps = generateFadeGradientProperties({
  topColors: { from: 'rgba(255, 0, 0, 0.5)', to: 'transparent' },
  bottomColors: { from: 'rgba(0, 0, 255, 0.5)', to: 'transparent' },
  leftColors: DEFAULT_GRADIENT_COLORS,
  rightColors: DEFAULT_GRADIENT_COLORS,
  showTop: true,
  showBottom: true,
  showLeft: false,
  showRight: false
})

console.log(gradientProps)
// Output: {
//   '--fade-top-gradient': 'linear-gradient(to bottom, rgba(255, 0, 0, 0.5), transparent)',
//   '--fade-bottom-gradient': 'linear-gradient(to top, rgba(0, 0, 255, 0.5), transparent)'
// }

// Generate CSS stylesheet for colored fades
const css = generateColoredFadeCSS('my-custom-fade-class')
console.log(css)
// Output: CSS string that can be injected into <style> tag

// Use in React component
function CustomGradientScroller({ items }) {
  React.useEffect(() => {
    // Inject CSS once on mount
    const style = document.createElement('style')
    style.textContent = generateColoredFadeCSS()
    document.head.appendChild(style)
    return () => document.head.removeChild(style)
  }, [])

  const gradientProps = generateFadeGradientProperties({
    topColors: { from: '#ff6b6b', to: 'transparent' },
    bottomColors: { from: '#4ecdc4', to: 'transparent' },
    showTop: true,
    showBottom: true,
    showLeft: false,
    showRight: false
  })

  return (
    <div
      className={COLORED_FADE_CLASS}
      style={{
        height: '400px',
        overflow: 'auto',
        position: 'relative',
        ...gradientProps
      }}
    >
      {items.map(item => <div key={item.id}>{item.name}</div>)}
    </div>
  )
}

<CustomGradientScroller items={items} />
```

--------------------------------

### Combined Vertical and Horizontal Scrolling

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

Demonstrates the use-scroll-fades hook handling both vertical and horizontal scrolling simultaneously. The mask-image approach requires no special configuration for this functionality, simplifying the implementation. Includes usage of `useRef` and `getContainerStyle` within a React component.

```tsx
import React, { useRef } from 'react';
import { useScrollFades } from '../src/useScrollFades'; // Assuming the hook is in ../src/useScrollFades

const HorizontalScrollExample = () => {
  const { containerRef, getContainerStyle } = useScrollFades({
    threshold: 12,
    fadeSize: 24
  });

  return (
    <div 
      ref={containerRef}
      style={{
        width: '400px',
        height: '200px',
        overflow: 'auto',
        ...getContainerStyle()
      }}
    >
      <div style={{ width: '800px', height: '100px', backgroundColor: 'lightblue' }}>
        Wide content that scrolls horizontally
      </div>
    </div>
  );
};

export default HorizontalScrollExample;
```

--------------------------------

### computeFadeState Utility Function (TypeScript)

Source: https://context7.com/cosmicthreepointo/use-scroll-fades/llms.txt

A pure utility function to manually calculate fade overlay visibility based on scroll metrics. It accepts scroll position, dimensions, and a threshold to determine if fades should be shown. Useful for custom scroll implementations or debugging.

```ts
import { computeFadeState } from '@gboue/use-scroll-fades'

// Manual calculation for custom scroll implementations
const scrollTop = 100
const scrollHeight = 1000
const clientHeight = 300
const scrollLeft = 50
const scrollWidth = 800
const clientWidth = 400
const threshold = 8

const state = computeFadeState(
  scrollTop,
  scrollHeight,
  clientHeight,
  scrollLeft,
  scrollWidth,
  clientWidth,
  threshold
)

console.log(state)
// Output: {
//   showTop: true,     // Not at top (scrollTop > threshold)
//   showBottom: true,  // Not at bottom (scrollTop + clientHeight < scrollHeight - threshold)
//   showLeft: true,    // Not at left (scrollLeft > threshold)
//   showRight: true    // Not at right (scrollLeft + clientWidth < scrollWidth - threshold)
// }

// At scroll top
const atTop = computeFadeState(0, 1000, 300, 0, 800, 400, 8)
console.log(atTop.showTop) // false - at top edge

// At scroll bottom
const atBottom = computeFadeState(700, 1000, 300, 0, 800, 400, 8)
console.log(atBottom.showBottom) // false - at bottom edge
```

--------------------------------

### Scroll Fade with Styled Components in React

Source: https://github.com/cosmicthreepointo/use-scroll-fades/blob/main/README.md

This snippet shows how to use the use-scroll-fades hook with Styled Components to create scrollable areas with fading overlays. It highlights how to integrate the hook's refs and style props to manage the visibility and appearance of top and bottom fade effects. The hook manages scroll events and state, while styled-components handles the visual styling and transitions.

```tsx
import React from 'react'
import styled from 'styled-components'
import { useScrollFades } from '@gboue/use-scroll-fades'

const Container = styled.div`
  position: relative;
  max-width: 640px;
`

const ScrollableArea = styled.div`
  overflow: auto;
  height: 300px;
  background: white;
  border-radius: 8px;
`

const FadeOverlay = styled.div<{ $visible: boolean; $position: 'top' | 'bottom' }>`
  position: absolute;
  left: 0;
  right: 0;
  height: 40px;
  pointer-events: none;
  opacity: ${props => props.$visible ? 1 : 0};
  transition: opacity 0.2s ease;
  
  ${props => props.$position === 'top' ? `
    top: 0;
    background: linear-gradient(to bottom, rgba(255,255,255,0.9), transparent);
  ` : `
    bottom: 0;
    background: linear-gradient(to top, rgba(255,255,255,0.9), transparent);
  `}
`

export default function StyledList({ items }) {
  // Note: Hook provides built-in smooth transitions
  // But you can also use styled-components transitions as shown above
  const { containerRef, state, getOverlayStyle } = useScrollFades({
    threshold: 10,
    transitionDuration: 250 // Slightly slower for demo
  })

  return (
    <Container>
      <ScrollableArea ref={containerRef}>
        {items.map((item, i) => <div key={i}>{item}</div>)}
      </ScrollableArea>
      
      {/* Option 1: Use hook's built-in animations */}
      <div style={{ 
        position: 'absolute', left: 0, right: 0, top: 0, height: 40,
        pointerEvents: 'none',
        ...getOverlayStyle('top')
      }} />
      <div style={{ 
        position: 'absolute', left: 0, right: 0, bottom: 0, height: 40,
        pointerEvents: 'none', 
        ...getOverlayStyle('bottom')
      }} />
      
      {/* Option 2: Or use styled-components animations */}
      {/* <FadeOverlay $visible={state.showTop} $position="top" />
      <FadeOverlay $visible={state.showBottom} $position="bottom" /> */}
    </Container>
  )
}

```