Skip to content

Commit 84a0902

Browse files
jscottsmithjscottsmith
committed
docs: llm improvements
1 parent db1987a commit 84a0902

29 files changed

Lines changed: 295 additions & 59 deletions

‎AGENTS.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# AGENTS.md
2+
3+
Guide for coding agents working in the **react-scroll-parallax** repository.
4+
5+
## Project
6+
7+
- **Package:** `react-scroll-parallax` (v4 beta — WAAPI / ScrollTimeline)
8+
- **Peer deps:** React 16.8+ / 17 / 18 / 19
9+
- **Install (v4):** `npm install react-scroll-parallax@beta`
10+
- **Build:** `pnpm build` (outputs to `dist/`)
11+
- **Tests:** `pnpm test`
12+
13+
## Documentation for agents
14+
15+
Prefer machine-readable docs over scraping the site:
16+
17+
- Index: https://react-scroll-parallax.damnthat.tv/llms.txt
18+
- Full bundle: https://react-scroll-parallax.damnthat.tv/llms-full.txt
19+
- Per-page markdown: https://react-scroll-parallax.damnthat.tv/docs/v4/**/*.md
20+
21+
Current docs target **v4 beta**. v3 docs remain on the site via the version dropdown.
22+
23+
## Quick start
24+
25+
```tsx
26+
import { ParallaxProvider, useParallax, Parallax } from 'react-scroll-parallax';
27+
28+
function App() {
29+
return (
30+
<ParallaxProvider>
31+
<MyContent />
32+
</ParallaxProvider>
33+
);
34+
}
35+
36+
function MyContent() {
37+
const { ref } = useParallax({ speed: -10 });
38+
return (
39+
<>
40+
<div ref={ref}>Hook example</div>
41+
<Parallax speed={10}>
42+
<div>Component example</div>
43+
</Parallax>
44+
</>
45+
);
46+
}
47+
```
48+
49+
`<ParallaxProvider>` must wrap any tree that uses parallax hooks or components.
50+
51+
## Key API
52+
53+
| Topic | Doc |
54+
| --- | --- |
55+
| Setup | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/usage |
56+
| All props | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/parallax-props |
57+
| `useParallax` | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/hooks/use-parallax |
58+
| `useParallaxController` | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/hooks/use-parallax-controller |
59+
| `<Parallax>` | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-component |
60+
| `<ParallaxBanner>` | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-banner-component |
61+
| `<ParallaxProvider>` | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-provider |
62+
| Next.js App Router | https://react-scroll-parallax.damnthat.tv/docs/v4/usage/next-13 |
63+
| v3 → v4 migration | https://react-scroll-parallax.damnthat.tv/docs/v4/migration-guides/v3-migration-guide |
64+
65+
## Source layout
66+
67+
```
68+
src/
69+
index.ts # Public exports
70+
hooks/ # useParallax, useParallaxController
71+
components/
72+
Parallax/ # <Parallax> component
73+
ParallaxBanner/ # <ParallaxBanner>, ParallaxBannerLayer
74+
ParallaxProvider/ # Context provider
75+
context/ParallaxContext.ts
76+
dist/ # Build output (published to npm)
77+
stories/ # Storybook examples
78+
documentation/ # Docusaurus docs site
79+
```
80+
81+
Underlying scroll engine: [parallax-controller](https://parallax-controller.damnthat.tv/docs/v2/intro).
82+
83+
## Common pitfalls
84+
85+
1. **Missing provider** — hooks/components throw or no-op without `<ParallaxProvider>`.
86+
2. **`<Parallax>` wrapper** — applies styles to its own wrapper `div`, not directly to children.
87+
3. **Cache updates** — call `parallaxController.update()` after route changes, image loads, or layout shifts.
88+
4. **Sticky elements** — parallax on sticky nodes causes issues; use `targetElement`, or fixed `startScroll` / `endScroll`.
89+
5. **v4 easing** — `easing` must be valid CSS/WAAPI timing values (not legacy preset strings like `easeInQuad`).
90+
6. **Horizontal scroll** — set `scrollAxis="horizontal"` on `<ParallaxProvider>`.

‎README.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,15 @@ npm install react-scroll-parallax
2424

2525
Uses the latest [Parallax Controller](https://parallax-controller.damnthat.tv/docs/v2/intro) built with **Web Animations API** for scroll-driven animations.
2626

27-
If you're upgrading from V3, here's a [migration guide to the v4 beta](/docs/v4/migration-guides/v3-migration-guide).
27+
If you're upgrading from V3, here's a [migration guide to the v4 beta](https://react-scroll-parallax.damnthat.tv/docs/v4/migration-guides/v3-migration-guide).
2828

2929
```
3030
npm install react-scroll-parallax@beta
3131
```
3232

3333
## Example
3434

35-
[Create effects](https://react-scroll-parallax.damnthat.tv/docs/examples/how-it-works) with a hook:
35+
[Create effects](https://react-scroll-parallax.damnthat.tv/docs/v4/examples/how-it-works) with a hook:
3636

3737
```jsx
3838
function Component() {
@@ -59,9 +59,9 @@ function Component() {
5959

6060
Read the [documentation](https://react-scroll-parallax.damnthat.tv/) for setup and usage instructions.
6161

62-
- [Usage](https://react-scroll-parallax.damnthat.tv/docs/usage/)
63-
- [Usage with NextJS 13](https://react-scroll-parallax.damnthat.tv/docs/usage/next-13)
64-
- [How it works](https://react-scroll-parallax.damnthat.tv/docs/examples/how-it-works)
62+
- [Usage](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/)
63+
- [Usage with NextJS 13](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/next-13)
64+
- [How it works](https://react-scroll-parallax.damnthat.tv/docs/v4/examples/how-it-works)
6565

6666
### Demos
6767

@@ -71,11 +71,11 @@ Read the [documentation](https://react-scroll-parallax.damnthat.tv/) for setup a
7171

7272
### Docs: Hooks
7373

74-
- [`useParallax()`](https://react-scroll-parallax.damnthat.tv/docs/usage/hooks/use-parallax)
75-
- [`useParallaxController()`](https://react-scroll-parallax.damnthat.tv/docs/usage/hooks/use-parallax-controller)
74+
- [`useParallax()`](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/hooks/use-parallax)
75+
- [`useParallaxController()`](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/hooks/use-parallax-controller)
7676

7777
### Docs: Components
7878

79-
- [`<Parallax>`](https://react-scroll-parallax.damnthat.tv/docs/usage/components/parallax-component)
80-
- [`<ParallaxBanner>`](https://react-scroll-parallax.damnthat.tv/docs/usage/components/parallax-banner-component)
81-
- [`<ParallaxProvider>`](https://react-scroll-parallax.damnthat.tv/docs/usage/components/parallax-provider)
79+
- [`<Parallax>`](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-component)
80+
- [`<ParallaxBanner>`](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-banner-component)
81+
- [`<ParallaxProvider>`](https://react-scroll-parallax.damnthat.tv/docs/v4/usage/components/parallax-provider)

‎documentation/docs/examples/advanced-banners.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
hide_title: true
33
title: Advanced Banners
44
sidebar_position: 6
5+
description: Advanced ParallaxBanner with translateY, scale, opacity, easing, and gradient overlay layers.
56
---
67

78
import { AdvancedBannerTop } from '/src/components/advanced-banner-top';

‎documentation/docs/examples/banners.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 5
3+
description: ParallaxBanner examples — single image, multi-layer, headline overlay, and embedded headline layers.
34
---
45

56
import { ParallaxBannerSingle } from '/src/components/parallax-banner-single';

‎documentation/docs/examples/custom-effects.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 3
3+
description: Custom scroll effects using onProgressChange to drive CSS variables and animate any property.
34
---
45

56
import { CustomEffect } from '/src/components/custom-effect';

‎documentation/docs/examples/easing.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 7
3+
description: Easing scroll effects with global easing props and per-effect cubic-bezier timing functions.
34
---
45

56
import { EasingDemo } from '/src/components/easing-demo';

‎documentation/docs/examples/horizontal-scroll.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 6
3+
description: Horizontal scroll parallax setup with scrollAxis horizontal and layered background demo.
34
---
45

56
import { ExampleHorizontalScroll } from '/src/components/example-horizontal-scroll';

‎documentation/docs/examples/how-it-works.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 1
3+
description: How scroll parallax works — speed, progress relative to the viewport, and combined CSS effects.
34
---
45

56
import { ElementProgress } from '/src/components/element-progress';

‎documentation/docs/examples/scroll-effects.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 2
3+
description: Rotation and scale scroll effects on z-axis, y-axis, and per-axis scale with easing.
34
---
45

56
import { ExampleRotation } from '/src/components/example-rotation';

‎documentation/docs/intro.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,19 @@ hide_title: true
33
title: 'React Scroll Parallax'
44
sidebar_label: 'Intro'
55
sidebar_position: 1
6+
description: Introduction to React Scroll Parallax v4 beta — install, quick examples, and links to usage docs.
67
---
78

89
import { IntroLogo } from '@site/src/components/intro-logo';
910

1011
<IntroLogo />
1112

13+
:::info Version
14+
15+
These docs describe **v4 beta** (WAAPI / ScrollTimeline). v3 docs are available via the version dropdown.
16+
17+
:::
18+
1219
[![NPM Version Latest](https://img.shields.io/npm/v/react-scroll-parallax/latest)](https://www.npmjs.com/package/react-scroll-parallax)
1320
[![NPM Downloads](https://img.shields.io/npm/dm/react-scroll-parallax)](https://www.npmjs.com/package/react-scroll-parallax)
1421
[![Codecov](https://codecov.io/gh/jscottsmith/react-scroll-parallax/branch/v3/graph/badge.svg)](https://codecov.io/gh/jscottsmith/react-scroll-parallax)

0 commit comments

Comments
 (0)