@trackunit/react-map 0.2.291 → 0.2.292
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/index.cjs.js +314 -133
- package/index.esm.js +314 -138
- package/migrations/entry.js.map +1 -0
- package/package.json +2 -2
- package/src/draw/__testHelpers.d.ts +43 -0
- package/src/draw/internal/useControlledDrawValue.d.ts +25 -0
- package/src/draw/internal/useDrawErrorReporting.d.ts +18 -0
- package/src/draw/internal/useForceIdleWhen.d.ts +8 -0
- package/src/draw/useDraw.d.ts +75 -16
- package/src/index.d.ts +4 -4
- package/src/layers/useFitToContent.d.ts +49 -5
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { type DrawError, type DrawErrors, type DrawMode, type DrawPort, type DrawValue } from "@trackunit/react-map-adapter-shared";
|
|
2
|
+
export declare const SQUARE: DrawValue;
|
|
3
|
+
export declare const TRIANGLE: DrawValue;
|
|
4
|
+
/** The square under the consumer's own id, as a form would hold it. */
|
|
5
|
+
export declare const FORM_SQUARE: DrawValue;
|
|
6
|
+
/** The engine's own rendering of a drawing: its ids and bookkeeping, same geometry. */
|
|
7
|
+
export declare const engineValue: (drawing: DrawValue) => DrawValue;
|
|
8
|
+
/**
|
|
9
|
+
* In-memory `DrawPort` implemented as a class, like the adapters do, so the hooks are
|
|
10
|
+
* also tested against methods that depend on `this` (an unbound call must not pass).
|
|
11
|
+
*/
|
|
12
|
+
export declare class FakePort implements DrawPort {
|
|
13
|
+
private mode;
|
|
14
|
+
private value;
|
|
15
|
+
private errors;
|
|
16
|
+
private readonly listeners;
|
|
17
|
+
setMode(next: DrawMode): void;
|
|
18
|
+
setValue(next: DrawValue): void;
|
|
19
|
+
getMode(): DrawMode;
|
|
20
|
+
getValue(): DrawValue;
|
|
21
|
+
getErrors(): DrawErrors;
|
|
22
|
+
subscribe(listener: () => void): () => void;
|
|
23
|
+
/** Simulates a user edit arriving from the engine. */
|
|
24
|
+
emit(next: DrawValue): void;
|
|
25
|
+
/** Simulates the controller filling or clearing one slot; null clears both. */
|
|
26
|
+
emitError(next: DrawError | null): void;
|
|
27
|
+
/** Clears the engine slot only, like a recovered engine does. */
|
|
28
|
+
clearEngineError(): void;
|
|
29
|
+
private notify;
|
|
30
|
+
}
|
|
31
|
+
export declare const createFakePort: () => FakePort;
|
|
32
|
+
export declare const createApi: (draw?: DrawPort) => {
|
|
33
|
+
actions: {
|
|
34
|
+
draw: Readonly<{
|
|
35
|
+
setMode: (mode: DrawMode) => void;
|
|
36
|
+
setValue: (value: DrawValue) => void;
|
|
37
|
+
getMode: () => DrawMode;
|
|
38
|
+
getValue: () => DrawValue;
|
|
39
|
+
getErrors: () => DrawErrors;
|
|
40
|
+
subscribe: (listener: () => void) => () => void;
|
|
41
|
+
}> | undefined;
|
|
42
|
+
};
|
|
43
|
+
};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { type DrawPort, type DrawValue } from "@trackunit/react-map-adapter-shared";
|
|
2
|
+
import type { CallHandler } from "./useDrawErrorReporting";
|
|
3
|
+
/**
|
|
4
|
+
* The controlled form's sync between `value`, the consumer's drawing, and the port, the
|
|
5
|
+
* map's. Does nothing while `value` is undefined (the uncontrolled form) or the adapter
|
|
6
|
+
* has no port.
|
|
7
|
+
*
|
|
8
|
+
* The prop is the source of truth on every render: `value` is compared with the port's
|
|
9
|
+
* value by geometry (identity-cached, so the comparison runs only when either side
|
|
10
|
+
* changed) and pushed when they differ. The consumer's echo of an edit, the same
|
|
11
|
+
* geometry under its own ids, pushes nothing; the same `value` object rendered again
|
|
12
|
+
* after an edit the consumer did not take puts it back on the map.
|
|
13
|
+
*
|
|
14
|
+
* The port's own changes, a polygon the user finished, edited or deleted, or the Clear
|
|
15
|
+
* control, are reported through `onChange` inside `flushSync`, as React does for its own
|
|
16
|
+
* controlled inputs: the consumer's state is committed before any other render (the
|
|
17
|
+
* hook's own mode or error snapshot, a camera or focus snapshot elsewhere) can see the
|
|
18
|
+
* old `value` and push it back. Only the map's own changes are reported; a notification
|
|
19
|
+
* whose geometry the hook itself pushed or already reported is an echo and is not
|
|
20
|
+
* reported, so the hook's own pushes from effects never reach `flushSync`.
|
|
21
|
+
*
|
|
22
|
+
* Nothing here subscribes to the port's value for rendering: the controlled form renders
|
|
23
|
+
* an edit through the consumer's `onChange` only.
|
|
24
|
+
*/
|
|
25
|
+
export declare const useControlledDrawValue: (port: DrawPort | undefined, value: DrawValue | undefined, onChange: ((value: DrawValue) => void) | undefined, callHandler: CallHandler) => void;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type DrawError, type DrawErrors } from "@trackunit/react-map-adapter-shared";
|
|
2
|
+
/**
|
|
3
|
+
* Runs a consumer callback (`onChange` or `onError`) so that one that throws is warned,
|
|
4
|
+
* reported once per mount to the app's error handler (`on-change-threw`, `on-error-threw`)
|
|
5
|
+
* and never stops what follows, as with `useHeatmap`'s `onError`.
|
|
6
|
+
*/
|
|
7
|
+
export type CallHandler = (name: "onChange" | "onError", run: () => void, detail?: unknown) => void;
|
|
8
|
+
/**
|
|
9
|
+
* Error reporting for `useDraw`. Each error slot is reported once per new object: to
|
|
10
|
+
* `onError` when given, else as a development warning, and to the app's error handler
|
|
11
|
+
* at most once per code per hook mount (like `useHeatmap`; a rejected stored boundary
|
|
12
|
+
* would re-report on every reconnect otherwise). A `value-rejected` verdict is reported
|
|
13
|
+
* too, deliberately: it is the only count of legacy boundaries the engine cannot
|
|
14
|
+
* render, kept until the Phase 2b pilot has run (ADR 0030).
|
|
15
|
+
*
|
|
16
|
+
* Returns `callHandler`, the guard the controlled form wraps `onChange` in.
|
|
17
|
+
*/
|
|
18
|
+
export declare const useDrawErrorReporting: (errors: DrawErrors, onError: ((error: DrawError) => void) | undefined) => CallHandler;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { DrawPort } from "@trackunit/react-map-adapter-shared";
|
|
2
|
+
/**
|
|
3
|
+
* Forces the port back to `"idle"` whenever `condition` becomes true, at mount included,
|
|
4
|
+
* and again for a port that arrives or is swapped in while it holds: a disabled hook must
|
|
5
|
+
* not leave the map in a drawing mode it can no longer exit, and closing the polygon that
|
|
6
|
+
* reaches the feature limit ends polygon mode so the next click does not start another one.
|
|
7
|
+
*/
|
|
8
|
+
export declare const useForceIdleWhen: (port: DrawPort | undefined, condition: boolean) => void;
|
package/src/draw/useDraw.d.ts
CHANGED
|
@@ -5,22 +5,23 @@ import type { MapApi } from "../core/types";
|
|
|
5
5
|
type DrawApi = Readonly<{
|
|
6
6
|
actions: Pick<MapApi["actions"], "draw">;
|
|
7
7
|
}>;
|
|
8
|
-
|
|
8
|
+
type UseDrawBaseOptions = Readonly<{
|
|
9
9
|
/**
|
|
10
10
|
* Hide the draw controls and force the map back to `"idle"` without unmounting
|
|
11
11
|
* the hook, for example while a feature flag is off. Default `true`.
|
|
12
12
|
*/
|
|
13
13
|
enabled?: boolean;
|
|
14
14
|
/**
|
|
15
|
-
* Most
|
|
15
|
+
* Most features the drawing may hold. Once `value` holds that many, the "Draw
|
|
16
16
|
* polygon" toggle is disabled with a reason and polygon mode ends by itself after
|
|
17
17
|
* the polygon that reaches the limit is closed; editing and clearing stay
|
|
18
18
|
* available. The library itself is multi-polygon: a site wizard sets `1` here
|
|
19
19
|
* (ADR 0030, decided 19 Oct 2026). Features the engine rejected count too, so a
|
|
20
|
-
* stored boundary that needs a redraw is cleared first.
|
|
21
|
-
* ignored
|
|
20
|
+
* stored boundary that needs a redraw is cleared first. A value below one is
|
|
21
|
+
* ignored with a development warning, since the type cannot rule it out.
|
|
22
|
+
* Default: no limit.
|
|
22
23
|
*/
|
|
23
|
-
|
|
24
|
+
maxFeatures?: number;
|
|
24
25
|
/**
|
|
25
26
|
* Called once per error the drawing reports (same shape as `useHeatmap`): the
|
|
26
27
|
* engine failed to load or update, or part of a committed value could not be
|
|
@@ -32,18 +33,45 @@ export type UseDrawOptions = Readonly<{
|
|
|
32
33
|
*/
|
|
33
34
|
onError?: (error: DrawError) => void;
|
|
34
35
|
}>;
|
|
35
|
-
|
|
36
|
+
/**
|
|
37
|
+
* The uncontrolled form: the map owns the drawing. Read it from the returned `value`
|
|
38
|
+
* and replace it with `setValue`.
|
|
39
|
+
*/
|
|
40
|
+
export interface UseDrawUncontrolledOptions extends UseDrawBaseOptions {
|
|
41
|
+
readonly value?: undefined;
|
|
42
|
+
readonly onChange?: undefined;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The controlled form: the consumer owns the drawing, as a form field does. The two
|
|
46
|
+
* options come together; one without the other is a type error.
|
|
47
|
+
*/
|
|
48
|
+
export interface UseDrawControlledOptions extends UseDrawBaseOptions {
|
|
49
|
+
/**
|
|
50
|
+
* The drawing the map shows, the source of truth on every render: whenever its
|
|
51
|
+
* geometry differs from what the map holds, it is pushed to the map. Handing an
|
|
52
|
+
* edit back under your own ids pushes nothing, so the edit is never interrupted;
|
|
53
|
+
* rendering the same object again after an edit you did not take puts it back on
|
|
54
|
+
* the map. The type is a `FeatureCollection` of `Polygon` features; the engine is
|
|
55
|
+
* stricter (one closed ring, no holes, no self-intersection) and reports a feature
|
|
56
|
+
* it cannot render through `onError` as `value-rejected`, keeping it in the value.
|
|
57
|
+
*/
|
|
58
|
+
readonly value: DrawValue;
|
|
59
|
+
/**
|
|
60
|
+
* Reports every change the map makes to the drawing, and nothing else: a polygon
|
|
61
|
+
* the user finished, edited or deleted, and the Clear control. A value the hook
|
|
62
|
+
* was given through `value` is never reported back, ids and properties aside, so
|
|
63
|
+
* no echo guard is needed on the consumer side.
|
|
64
|
+
*/
|
|
65
|
+
readonly onChange: (value: DrawValue) => void;
|
|
66
|
+
}
|
|
67
|
+
export type UseDrawOptions = UseDrawUncontrolledOptions | UseDrawControlledOptions;
|
|
68
|
+
type UseDrawBaseReturn = Readonly<{
|
|
36
69
|
/** False when the adapter has no drawing capability; `controls` is then empty. */
|
|
37
70
|
isSupported: boolean;
|
|
38
71
|
/** True while `mode` is not `"idle"`. Same signal as `api.state.drawing`. */
|
|
39
72
|
isDrawing: boolean;
|
|
40
73
|
/** Current drawing mode. */
|
|
41
74
|
mode: DrawMode;
|
|
42
|
-
/**
|
|
43
|
-
* Committed polygons as GeoJSON. Updates when the user finishes, edits or deletes a
|
|
44
|
-
* polygon, and when `setValue` is called.
|
|
45
|
-
*/
|
|
46
|
-
value: DrawValue;
|
|
47
75
|
/**
|
|
48
76
|
* The error to show now, or null: the engine failure while one is pending, else the
|
|
49
77
|
* verdict on the committed value. Read `errors` when both matter.
|
|
@@ -59,10 +87,6 @@ export type UseDrawReturn = Readonly<{
|
|
|
59
87
|
errors: DrawErrors;
|
|
60
88
|
/** Enter a drawing mode; `"idle"` ends drawing. */
|
|
61
89
|
setMode: (mode: DrawMode) => void;
|
|
62
|
-
/** Replace the committed polygons (controlled-input style). */
|
|
63
|
-
setValue: (value: DrawValue) => void;
|
|
64
|
-
/** Remove every polygon and return to `"idle"`. */
|
|
65
|
-
clear: () => void;
|
|
66
90
|
/**
|
|
67
91
|
* Ready-made controls for the `tools` area: a "Draw polygon" toggle, an "Edit
|
|
68
92
|
* polygon" toggle and a "Clear drawing" button. Empty when drawing is unsupported
|
|
@@ -70,6 +94,32 @@ export type UseDrawReturn = Readonly<{
|
|
|
70
94
|
*/
|
|
71
95
|
controls: ReadonlyArray<ControlConfig>;
|
|
72
96
|
}>;
|
|
97
|
+
/** What `useDraw` returns in the uncontrolled form, where the map owns the drawing. */
|
|
98
|
+
export interface UseDrawUncontrolledReturn extends UseDrawBaseReturn {
|
|
99
|
+
/**
|
|
100
|
+
* The committed polygons as the map holds them, GeoJSON. Updates when the user
|
|
101
|
+
* finishes, edits or deletes a polygon, and when `setValue` is called.
|
|
102
|
+
*/
|
|
103
|
+
readonly value: DrawValue;
|
|
104
|
+
/** Replace the committed polygons. */
|
|
105
|
+
readonly setValue: (value: DrawValue) => void;
|
|
106
|
+
/** Remove every polygon and return to `"idle"`. */
|
|
107
|
+
readonly clear: () => void;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* What `useDraw` returns in the controlled form, where the consumer owns the drawing.
|
|
111
|
+
* There is no value here: the `value` option is the drawing, and it changes by
|
|
112
|
+
* changing that option, so `setValue` and `clear` have no place either. An edit the
|
|
113
|
+
* consumer does not want is rejected by rendering the value it holds.
|
|
114
|
+
*/
|
|
115
|
+
export interface UseDrawControlledReturn extends UseDrawBaseReturn {
|
|
116
|
+
/**
|
|
117
|
+
* End the drawing mode (`"idle"`) and nothing else: an in-progress polygon is
|
|
118
|
+
* discarded, the committed drawing stays `value`.
|
|
119
|
+
*/
|
|
120
|
+
readonly stopDrawing: () => void;
|
|
121
|
+
}
|
|
122
|
+
export type UseDrawReturn = UseDrawUncontrolledReturn | UseDrawControlledReturn;
|
|
73
123
|
/**
|
|
74
124
|
* Ids of the controls `useDraw` returns, for a consumer that filters or replaces one of them
|
|
75
125
|
* (a wizard that confirms before clearing, for instance).
|
|
@@ -87,6 +137,11 @@ export declare const DRAW_CONTROL_IDS: {
|
|
|
87
137
|
* `useControls`). Feature code sees GeoJSON in and GeoJSON out; the engine behind
|
|
88
138
|
* the adapter is never exposed.
|
|
89
139
|
*
|
|
140
|
+
* Two forms, told apart by the options and each with its own return type:
|
|
141
|
+
* uncontrolled, where the map owns the drawing (`value` and `setValue` on the
|
|
142
|
+
* return), and controlled, where the consumer owns it (`value` and `onChange` in
|
|
143
|
+
* the options, as a form field; `stopDrawing` on the return).
|
|
144
|
+
*
|
|
90
145
|
* @example
|
|
91
146
|
* ```tsx
|
|
92
147
|
* const [Map, api] = useMap(adapter);
|
|
@@ -100,5 +155,9 @@ export declare const DRAW_CONTROL_IDS: {
|
|
|
100
155
|
* );
|
|
101
156
|
* ```
|
|
102
157
|
*/
|
|
103
|
-
export declare
|
|
158
|
+
export declare function useDraw(api: DrawApi, options: UseDrawControlledOptions): UseDrawControlledReturn;
|
|
159
|
+
/** The uncontrolled form: the map owns the drawing. */
|
|
160
|
+
export declare function useDraw(api: DrawApi, options?: UseDrawUncontrolledOptions): UseDrawUncontrolledReturn;
|
|
161
|
+
/** Either form, for a wrapper that forwards `UseDrawOptions` as given; narrow the result on `"stopDrawing" in draw`. */
|
|
162
|
+
export declare function useDraw(api: DrawApi, options?: UseDrawOptions): UseDrawReturn;
|
|
104
163
|
export {};
|
package/src/index.d.ts
CHANGED
|
@@ -16,9 +16,9 @@ export type { ControlStackItem } from "./controls/defineControlStack";
|
|
|
16
16
|
export type { UseControlsAreas } from "./controls/types";
|
|
17
17
|
export { useControls } from "./controls/useControls";
|
|
18
18
|
export { useDefaultControls, type UseDefaultControlsOptions } from "./controls/useDefaultControls";
|
|
19
|
-
export { EMPTY_DRAW_VALUE } from "@trackunit/react-map-adapter-shared";
|
|
20
|
-
export type { DrawEngineError, DrawError, DrawErrorCode, DrawErrors, DrawMode, DrawPort, DrawValue, DrawValueRejection, } from "@trackunit/react-map-adapter-shared";
|
|
21
|
-
export { DRAW_CONTROL_IDS, useDraw, type UseDrawOptions, type UseDrawReturn } from "./draw/useDraw";
|
|
19
|
+
export { EMPTY_DRAW_VALUE, toDrawValue } from "@trackunit/react-map-adapter-shared";
|
|
20
|
+
export type { DrawEngineError, DrawError, DrawErrorCode, DrawErrors, DrawFeature, DrawMode, DrawPort, DrawValue, DrawValueRejection, } from "@trackunit/react-map-adapter-shared";
|
|
21
|
+
export { DRAW_CONTROL_IDS, useDraw, type UseDrawControlledOptions, type UseDrawControlledReturn, type UseDrawOptions, type UseDrawReturn, type UseDrawUncontrolledOptions, type UseDrawUncontrolledReturn, } from "./draw/useDraw";
|
|
22
22
|
export { DEFAULT_APPEARANCE_PERSISTENCE_KEY } from "./appearance/appearanceTypes";
|
|
23
23
|
export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";
|
|
24
24
|
export { useMapAppearanceControls } from "./appearance/useMapAppearanceControls";
|
|
@@ -57,7 +57,7 @@ export { type ContendedShape, type ResolveShapeStackOrder } from "./layers/useSh
|
|
|
57
57
|
export { useImageOverlay, type UseImageOverlayOptions, type UseImageOverlayReturn, } from "./layers/image-overlay/useImageOverlay";
|
|
58
58
|
export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, type MapFocusTierDisplay, } from "./layers/mapFocus";
|
|
59
59
|
export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";
|
|
60
|
-
export { useFitToContent, type FitToContentOptions, type FitToContentResult } from "./layers/useFitToContent";
|
|
60
|
+
export { NO_FIT_TARGETS, useFitToContent, type FitTarget, type FitToContentOptions, type FitToContentResult, } from "./layers/useFitToContent";
|
|
61
61
|
export { useHeatmap, type HeatmapStyle, type UseHeatmapOptions, type UseHeatmapReturn, } from "./layers/useHeatmap/useHeatmap";
|
|
62
62
|
export { useLabelPlacement, type LabelPlacementCluster, type UseLabelPlacementParams, } from "./layers/useLabelPlacement";
|
|
63
63
|
export { useLayers, type UseLayersReturn } from "./layers/useLayers";
|
|
@@ -1,5 +1,29 @@
|
|
|
1
|
+
import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
|
|
1
2
|
import type { MapApi } from "../core/types";
|
|
2
|
-
import type { LayerHandle } from "./types";
|
|
3
|
+
import type { FitParticipation, LayerHandle } from "./types";
|
|
4
|
+
/**
|
|
5
|
+
* Something to fit that is not a layer but takes part in fit-to-content as one would: a
|
|
6
|
+
* boundary the drawing engine renders, a server-side extent, a saved viewport.
|
|
7
|
+
*/
|
|
8
|
+
export type FitTarget = Readonly<{
|
|
9
|
+
/** The bounds, or null while there are none. */
|
|
10
|
+
bounds: GeoJsonBbox | null;
|
|
11
|
+
/**
|
|
12
|
+
* True while the bounds are still being fetched. The initial fit waits for every
|
|
13
|
+
* loading target, as it waits for a layer that loads data, up to `timeout`. It is an
|
|
14
|
+
* input of the fit, read on every render until the fit has run, so a query that only
|
|
15
|
+
* starts once the map is ready is waited for too. Keep it true until `bounds` is set
|
|
16
|
+
* in the same render: a target that is not loading and has no bounds has nothing to
|
|
17
|
+
* frame, and once every target has settled the one-shot fit is spent. Default: false.
|
|
18
|
+
*/
|
|
19
|
+
loading?: boolean;
|
|
20
|
+
/** When the target takes part, with the same meaning as a layer's. Default: `"all"`. */
|
|
21
|
+
fitParticipation?: FitParticipation;
|
|
22
|
+
/** Named in the timeout warning when still loading, as a layer is. Default: `"target"`. */
|
|
23
|
+
name?: string;
|
|
24
|
+
}>;
|
|
25
|
+
/** No targets. Stable reference for consumers that sometimes have none to pass. */
|
|
26
|
+
export declare const NO_FIT_TARGETS: ReadonlyArray<FitTarget>;
|
|
3
27
|
/**
|
|
4
28
|
* Options for the `useFitToContent` hook.
|
|
5
29
|
*/
|
|
@@ -12,6 +36,13 @@ export type FitToContentOptions = Readonly<{
|
|
|
12
36
|
maxZoom?: number;
|
|
13
37
|
/** Timeout in ms before fitting with whatever data is available. Default: 10000 */
|
|
14
38
|
timeout?: number;
|
|
39
|
+
/**
|
|
40
|
+
* Targets that are not layers, merged with the layers' bounds. Each one is waited
|
|
41
|
+
* for while `loading` and filtered by `fitParticipation`, as a layer is. The array is
|
|
42
|
+
* an input of the fit, so memoize it: a new array per render re-runs the fit check
|
|
43
|
+
* (cheap, but needless) and changes `fitNow`. Default: none.
|
|
44
|
+
*/
|
|
45
|
+
targets?: ReadonlyArray<FitTarget>;
|
|
15
46
|
}>;
|
|
16
47
|
/**
|
|
17
48
|
* Return type of the `useFitToContent` hook.
|
|
@@ -21,18 +52,25 @@ export type FitToContentResult = Readonly<{
|
|
|
21
52
|
hasFitted: boolean;
|
|
22
53
|
/** True while waiting for participating layers to load before the initial fit. */
|
|
23
54
|
isWaiting: boolean;
|
|
24
|
-
/** Manually trigger a fit-to-content. Animates. Only includes `fitParticipation: "all"` layers. */
|
|
55
|
+
/** Manually trigger a fit-to-content. Animates. Only includes `fitParticipation: "all"` layers and targets. */
|
|
25
56
|
fitNow: () => void;
|
|
26
57
|
}>;
|
|
27
58
|
/**
|
|
28
59
|
* `useFitToContent` -- orchestrates a one-time viewport fit once all
|
|
29
|
-
* participating layers have loaded their initial data.
|
|
60
|
+
* participating layers (and targets) have loaded their initial data.
|
|
30
61
|
*
|
|
31
62
|
* Only layers with `fitParticipation !== "none"` are waited on and included
|
|
32
63
|
* in the initial fit. `fitNow()` only includes `fitParticipation: "all"` layers.
|
|
33
64
|
*
|
|
65
|
+
* Content that is not a layer joins through `targets`: a boundary the drawing
|
|
66
|
+
* engine renders, a server-side extent. A target is filtered by its
|
|
67
|
+
* `fitParticipation` as a layer is, and waited for while `loading`: the fit is
|
|
68
|
+
* derived from the map's readiness, the layers' readiness and the targets on every
|
|
69
|
+
* render until it has run, so a target that starts loading once the map is ready
|
|
70
|
+
* holds the fit until it settles or the timeout fires.
|
|
71
|
+
*
|
|
34
72
|
* A configurable timeout (default 10s) ensures the map fits to whatever
|
|
35
|
-
* data is available if some layers are slow.
|
|
73
|
+
* data is available if some layers or targets are slow.
|
|
36
74
|
*
|
|
37
75
|
* When using this hook alongside an adapter's `initialViewport`, note that the
|
|
38
76
|
* initial viewport serves as a loading-state viewport and will be overridden
|
|
@@ -44,7 +82,13 @@ export type FitToContentResult = Readonly<{
|
|
|
44
82
|
* const shapes = useShapes({ id: "zones", ..., fitParticipation: "none" });
|
|
45
83
|
* const layers = useLayers(api, [markers, shapes]);
|
|
46
84
|
*
|
|
47
|
-
*
|
|
85
|
+
* // Memoized: the array is an input of the fit, so a new one per render would
|
|
86
|
+
* // re-run the fit check and change `fitNow`.
|
|
87
|
+
* const targets = useMemo(
|
|
88
|
+
* (): ReadonlyArray<FitTarget> => [{ bounds: storedBoundaryBbox, fitParticipation: "initial" }],
|
|
89
|
+
* [storedBoundaryBbox]
|
|
90
|
+
* );
|
|
91
|
+
* const { hasFitted, isWaiting, fitNow } = useFitToContent(api, layers.handles, { targets });
|
|
48
92
|
*
|
|
49
93
|
* return (
|
|
50
94
|
* <Map>
|