domet 1.0.4 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -28
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,20 +1,24 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Domet
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Introduction
|
|
4
|
+
|
|
5
|
+
Domet is a lightweight React hook built for scroll-driven interfaces. Use it for classic scroll-spy, but also for progress indicators, lazy section loading, or any UI that needs reliable section awareness.
|
|
4
6
|
|
|
5
7
|
Lightweight under the hood: a tight scroll loop and hysteresis for stable, flicker-free section tracking.
|
|
6
8
|
|
|
7
9
|
For the source code, check out the [GitHub](https://github.com/blksmr/domet).
|
|
8
10
|
|
|
9
|
-
## Installation
|
|
11
|
+
## Installation
|
|
12
|
+
Install the package from your command line.
|
|
10
13
|
|
|
11
14
|
```bash
|
|
12
15
|
npm install domet
|
|
13
16
|
```
|
|
14
17
|
|
|
15
|
-
##
|
|
18
|
+
## Usage
|
|
19
|
+
Basic example of how to use the hook.
|
|
16
20
|
|
|
17
|
-
```tsx
|
|
21
|
+
```tsx showLineNumbers
|
|
18
22
|
import { useDomet } from 'domet'
|
|
19
23
|
|
|
20
24
|
const sections = ['intro', 'features', 'api']
|
|
@@ -42,41 +46,41 @@ function Page() {
|
|
|
42
46
|
|
|
43
47
|
## API Reference
|
|
44
48
|
|
|
45
|
-
|
|
49
|
+
## Arguments
|
|
46
50
|
|
|
47
|
-
|
|
|
48
|
-
|
|
49
|
-
| `sectionIds` | `string[]` | Array of section IDs to track |
|
|
50
|
-
| `containerRef` | `RefObject<HTMLElement> \| null` | Scrollable container (defaults to
|
|
51
|
-
| `options` | `DometOptions` | Configuration options |
|
|
51
|
+
| Prop | Type | Default | Description |
|
|
52
|
+
|------|------|---------|-------------|
|
|
53
|
+
| `sectionIds` | `string[]` | — | Array of section IDs to track |
|
|
54
|
+
| `containerRef` | `RefObject<HTMLElement> \| null` | `null` | Scrollable container (defaults to window) |
|
|
55
|
+
| `options` | `DometOptions` | `{}` | Configuration options |
|
|
52
56
|
|
|
53
|
-
|
|
57
|
+
## Options
|
|
54
58
|
|
|
55
|
-
|
|
|
56
|
-
|
|
59
|
+
| Prop | Type | Default | Description |
|
|
60
|
+
|------|------|---------|-------------|
|
|
57
61
|
| `offset` | `number` | `0` | Trigger offset from top in pixels |
|
|
58
62
|
| `offsetRatio` | `number` | `0.08` | Viewport ratio for trigger line calculation |
|
|
59
63
|
| `debounceMs` | `number` | `10` | Throttle delay in milliseconds |
|
|
60
64
|
| `visibilityThreshold` | `number` | `0.6` | Minimum visibility ratio (0-1) for section to get priority |
|
|
61
65
|
| `hysteresisMargin` | `number` | `150` | Score margin to prevent rapid section switching |
|
|
62
|
-
| `behavior` | `'smooth' \| 'instant' \| 'auto'` | `'auto'` | Scroll behavior.
|
|
66
|
+
| `behavior` | `'smooth' \| 'instant' \| 'auto'` | `'auto'` | Scroll behavior. 'auto' respects prefers-reduced-motion |
|
|
63
67
|
|
|
64
|
-
|
|
68
|
+
## Callbacks
|
|
65
69
|
|
|
66
|
-
|
|
|
67
|
-
|
|
70
|
+
| Prop | Type | Description |
|
|
71
|
+
|------|------|-------------|
|
|
68
72
|
| `onActiveChange` | `(id: string \| null, prevId: string \| null) => void` | Called when active section changes |
|
|
69
73
|
| `onSectionEnter` | `(id: string) => void` | Called when a section enters the viewport |
|
|
70
74
|
| `onSectionLeave` | `(id: string) => void` | Called when a section leaves the viewport |
|
|
71
75
|
| `onScrollStart` | `() => void` | Called when scrolling starts |
|
|
72
76
|
| `onScrollEnd` | `() => void` | Called when scrolling stops |
|
|
73
77
|
|
|
74
|
-
|
|
78
|
+
## Return Value
|
|
75
79
|
|
|
76
|
-
|
|
|
77
|
-
|
|
80
|
+
| Prop | Type | Description |
|
|
81
|
+
|------|------|-------------|
|
|
78
82
|
| `activeId` | `string \| null` | ID of the currently active section |
|
|
79
|
-
| `activeIndex` | `number` | Index of the active section in
|
|
83
|
+
| `activeIndex` | `number` | Index of the active section in sectionIds (-1 if none) |
|
|
80
84
|
| `scroll` | `ScrollState` | Global scroll state |
|
|
81
85
|
| `sections` | `Record<string, SectionState>` | Per-section state indexed by ID |
|
|
82
86
|
| `sectionProps` | `(id: string) => SectionProps` | Props to spread on section elements |
|
|
@@ -86,7 +90,7 @@ function Page() {
|
|
|
86
90
|
|
|
87
91
|
## Types
|
|
88
92
|
|
|
89
|
-
|
|
93
|
+
## ScrollState
|
|
90
94
|
|
|
91
95
|
Global scroll information updated on every scroll event.
|
|
92
96
|
|
|
@@ -103,7 +107,7 @@ type ScrollState = {
|
|
|
103
107
|
}
|
|
104
108
|
```
|
|
105
109
|
|
|
106
|
-
|
|
110
|
+
## SectionState
|
|
107
111
|
|
|
108
112
|
Per-section state available for each tracked section.
|
|
109
113
|
|
|
@@ -125,7 +129,7 @@ type SectionBounds = {
|
|
|
125
129
|
|
|
126
130
|
## Examples
|
|
127
131
|
|
|
128
|
-
|
|
132
|
+
## With Callbacks
|
|
129
133
|
|
|
130
134
|
```tsx
|
|
131
135
|
const { activeId } = useDomet(sections, null, {
|
|
@@ -138,7 +142,7 @@ const { activeId } = useDomet(sections, null, {
|
|
|
138
142
|
})
|
|
139
143
|
```
|
|
140
144
|
|
|
141
|
-
|
|
145
|
+
## Using Scroll State
|
|
142
146
|
|
|
143
147
|
```tsx
|
|
144
148
|
const { scroll, sections } = useDomet(sectionIds)
|
|
@@ -152,7 +156,7 @@ const { scroll, sections } = useDomet(sectionIds)
|
|
|
152
156
|
))}
|
|
153
157
|
```
|
|
154
158
|
|
|
155
|
-
|
|
159
|
+
## Custom Container
|
|
156
160
|
|
|
157
161
|
```tsx
|
|
158
162
|
const containerRef = useRef<HTMLDivElement>(null)
|
|
@@ -165,7 +169,7 @@ return (
|
|
|
165
169
|
)
|
|
166
170
|
```
|
|
167
171
|
|
|
168
|
-
|
|
172
|
+
## Fine-tuning Behavior
|
|
169
173
|
|
|
170
174
|
```tsx
|
|
171
175
|
useDomet(sections, null, {
|