@usefy/use-geolocation 0.0.28 → 0.0.29
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 +42 -62
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -119,47 +119,47 @@ A hook that manages geolocation state with real-time tracking and utility functi
|
|
|
119
119
|
|
|
120
120
|
#### Parameters
|
|
121
121
|
|
|
122
|
-
| Parameter | Type
|
|
123
|
-
| --------- |
|
|
124
|
-
| `options`
|
|
122
|
+
| Parameter | Type | Description |
|
|
123
|
+
| --------- | ----------------------- | ----------------------------- |
|
|
124
|
+
| `options` | `UseGeolocationOptions` | Optional configuration object |
|
|
125
125
|
|
|
126
126
|
#### Options
|
|
127
127
|
|
|
128
|
-
| Option
|
|
129
|
-
|
|
|
130
|
-
| `enableHighAccuracy` | `boolean`
|
|
131
|
-
| `maximumAge`
|
|
132
|
-
| `timeout`
|
|
133
|
-
| `watch`
|
|
134
|
-
| `immediate`
|
|
135
|
-
| `onSuccess`
|
|
136
|
-
| `onError`
|
|
137
|
-
| `onPositionChange`
|
|
138
|
-
| `onPermissionChange` | `(state: PermissionState) => void`
|
|
128
|
+
| Option | Type | Default | Description |
|
|
129
|
+
| -------------------- | ----------------------------------- | ------- | ----------------------------------------------------------- |
|
|
130
|
+
| `enableHighAccuracy` | `boolean` | `false` | Enable high accuracy mode (uses GPS, consumes more battery) |
|
|
131
|
+
| `maximumAge` | `number` | `0` | Maximum age of cached position in milliseconds |
|
|
132
|
+
| `timeout` | `number` | `30000` | Timeout in milliseconds for position request |
|
|
133
|
+
| `watch` | `boolean` | `false` | Start watching position immediately on mount |
|
|
134
|
+
| `immediate` | `boolean` | `true` | Get initial position immediately on mount |
|
|
135
|
+
| `onSuccess` | `(position: GeoPosition) => void` | — | Callback when position is successfully retrieved |
|
|
136
|
+
| `onError` | `(error: GeolocationError) => void` | — | Callback when an error occurs |
|
|
137
|
+
| `onPositionChange` | `(position: GeoPosition) => void` | — | Callback when position changes (during watch mode) |
|
|
138
|
+
| `onPermissionChange` | `(state: PermissionState) => void` | — | Callback when permission state changes |
|
|
139
139
|
|
|
140
140
|
#### Returns `UseGeolocationReturn`
|
|
141
141
|
|
|
142
|
-
| Property
|
|
143
|
-
|
|
|
144
|
-
| `position`
|
|
145
|
-
| `loading`
|
|
146
|
-
| `error`
|
|
147
|
-
| `permission`
|
|
148
|
-
| `isSupported`
|
|
149
|
-
| `getCurrentPosition` | `() => void`
|
|
150
|
-
| `watchPosition` | `() => void`
|
|
151
|
-
| `clearWatch`
|
|
152
|
-
| `distanceFrom`
|
|
153
|
-
| `bearingTo`
|
|
142
|
+
| Property | Type | Description |
|
|
143
|
+
| -------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
144
|
+
| `position` | `GeoPosition \| null` | Current position data (null if not yet retrieved) |
|
|
145
|
+
| `loading` | `boolean` | Loading state (true while fetching position) |
|
|
146
|
+
| `error` | `GeolocationError \| null` | Error object (null if no error) |
|
|
147
|
+
| `permission` | `PermissionState` | Current permission state (`prompt`, `granted`, `denied`, `unavailable`) |
|
|
148
|
+
| `isSupported` | `boolean` | Whether geolocation is supported in this environment |
|
|
149
|
+
| `getCurrentPosition` | `() => void` | Manually get current position (one-time request) |
|
|
150
|
+
| `watchPosition` | `() => void` | Start watching position for real-time updates |
|
|
151
|
+
| `clearWatch` | `() => void` | Stop watching position |
|
|
152
|
+
| `distanceFrom` | `(lat: number, lon: number) => number \| null` | Calculate distance from current position to target coordinates in meters |
|
|
153
|
+
| `bearingTo` | `(lat: number, lon: number) => number \| null` | Calculate bearing/direction from current position to target coordinates (0-360 degrees) |
|
|
154
154
|
|
|
155
155
|
#### Error Codes
|
|
156
156
|
|
|
157
|
-
| Code
|
|
158
|
-
|
|
|
159
|
-
| `PERMISSION_DENIED`
|
|
160
|
-
| `POSITION_UNAVAILABLE` | Position information unavailable
|
|
161
|
-
| `TIMEOUT`
|
|
162
|
-
| `NOT_SUPPORTED`
|
|
157
|
+
| Code | Description |
|
|
158
|
+
| ---------------------- | ------------------------------------------------ |
|
|
159
|
+
| `PERMISSION_DENIED` | User denied geolocation permission |
|
|
160
|
+
| `POSITION_UNAVAILABLE` | Position information unavailable |
|
|
161
|
+
| `TIMEOUT` | Position request timed out |
|
|
162
|
+
| `NOT_SUPPORTED` | Geolocation is not supported in this environment |
|
|
163
163
|
|
|
164
164
|
---
|
|
165
165
|
|
|
@@ -209,7 +209,7 @@ function ManualLocation() {
|
|
|
209
209
|
</button>
|
|
210
210
|
<button onClick={watchPosition}>Start Tracking</button>
|
|
211
211
|
<button onClick={clearWatch}>Stop Tracking</button>
|
|
212
|
-
|
|
212
|
+
|
|
213
213
|
{position && (
|
|
214
214
|
<p>
|
|
215
215
|
{position.coords.latitude}, {position.coords.longitude}
|
|
@@ -254,9 +254,9 @@ function LiveTracking() {
|
|
|
254
254
|
<button onClick={handleStop} disabled={!isTracking}>
|
|
255
255
|
Stop Tracking
|
|
256
256
|
</button>
|
|
257
|
-
|
|
257
|
+
|
|
258
258
|
{isTracking && <p>🔴 Live tracking active</p>}
|
|
259
|
-
|
|
259
|
+
|
|
260
260
|
{position && (
|
|
261
261
|
<p>
|
|
262
262
|
{position.coords.latitude.toFixed(6)},{" "}
|
|
@@ -278,15 +278,13 @@ function DistanceToDestination() {
|
|
|
278
278
|
|
|
279
279
|
// New York City coordinates
|
|
280
280
|
const nyLat = 40.7128;
|
|
281
|
-
const nyLon = -74.
|
|
281
|
+
const nyLon = -74.006;
|
|
282
282
|
|
|
283
283
|
const distance = distanceFrom(nyLat, nyLon);
|
|
284
284
|
|
|
285
285
|
return (
|
|
286
286
|
<div>
|
|
287
|
-
{distance && (
|
|
288
|
-
<p>Distance to NYC: {(distance / 1000).toFixed(2)} km</p>
|
|
289
|
-
)}
|
|
287
|
+
{distance && <p>Distance to NYC: {(distance / 1000).toFixed(2)} km</p>}
|
|
290
288
|
</div>
|
|
291
289
|
);
|
|
292
290
|
}
|
|
@@ -345,11 +343,7 @@ function HighAccuracyLocation() {
|
|
|
345
343
|
|
|
346
344
|
return (
|
|
347
345
|
<div>
|
|
348
|
-
{position && (
|
|
349
|
-
<p>
|
|
350
|
-
High accuracy: {position.coords.accuracy.toFixed(1)}m
|
|
351
|
-
</p>
|
|
352
|
-
)}
|
|
346
|
+
{position && <p>High accuracy: {position.coords.accuracy.toFixed(1)}m</p>}
|
|
353
347
|
</div>
|
|
354
348
|
);
|
|
355
349
|
}
|
|
@@ -388,7 +382,7 @@ function RobustLocation() {
|
|
|
388
382
|
immediate: false,
|
|
389
383
|
onError: (err) => {
|
|
390
384
|
console.error("Geolocation error:", err.code, err.message);
|
|
391
|
-
|
|
385
|
+
|
|
392
386
|
if (err.code === "PERMISSION_DENIED") {
|
|
393
387
|
alert("Please allow location access");
|
|
394
388
|
} else if (err.code === "TIMEOUT") {
|
|
@@ -400,14 +394,14 @@ function RobustLocation() {
|
|
|
400
394
|
return (
|
|
401
395
|
<div>
|
|
402
396
|
<button onClick={getCurrentPosition}>Get Location</button>
|
|
403
|
-
|
|
397
|
+
|
|
404
398
|
{error && (
|
|
405
399
|
<div className="error">
|
|
406
400
|
<p>Error: {error.code}</p>
|
|
407
401
|
<p>{error.message}</p>
|
|
408
402
|
</div>
|
|
409
403
|
)}
|
|
410
|
-
|
|
404
|
+
|
|
411
405
|
{position && (
|
|
412
406
|
<p>
|
|
413
407
|
{position.coords.latitude}, {position.coords.longitude}
|
|
@@ -433,7 +427,7 @@ function AutoTracking() {
|
|
|
433
427
|
<div>
|
|
434
428
|
<p>Auto-tracking is active</p>
|
|
435
429
|
<button onClick={clearWatch}>Stop</button>
|
|
436
|
-
|
|
430
|
+
|
|
437
431
|
{position && (
|
|
438
432
|
<p>
|
|
439
433
|
{position.coords.latitude.toFixed(6)},{" "}
|
|
@@ -601,19 +595,6 @@ This package maintains comprehensive test coverage to ensure reliability and sta
|
|
|
601
595
|
|
|
602
596
|
</details>
|
|
603
597
|
|
|
604
|
-
### Running Tests
|
|
605
|
-
|
|
606
|
-
```bash
|
|
607
|
-
# Run all tests
|
|
608
|
-
pnpm test
|
|
609
|
-
|
|
610
|
-
# Run tests in watch mode
|
|
611
|
-
pnpm test:watch
|
|
612
|
-
|
|
613
|
-
# Run tests with coverage report
|
|
614
|
-
pnpm test --coverage
|
|
615
|
-
```
|
|
616
|
-
|
|
617
598
|
---
|
|
618
599
|
|
|
619
600
|
## Browser Compatibility
|
|
@@ -642,4 +623,3 @@ This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorep
|
|
|
642
623
|
<p align="center">
|
|
643
624
|
<sub>Built with care by the usefy team</sub>
|
|
644
625
|
</p>
|
|
645
|
-
|
package/package.json
CHANGED