@tileflow/react 0.1.0-alpha.24 → 0.1.0-alpha.25
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 +187 -223
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,12 +1,80 @@
|
|
|
1
1
|
# @tileflow/react
|
|
2
2
|
|
|
3
|
-
React components for
|
|
3
|
+
React components for interactive Tileflow maps, annotations, and static-image display.
|
|
4
|
+
Interactive maps use MapLibre GL JS; browser components read prepared assets rather than compiling
|
|
5
|
+
`tileflow.config.ts`.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
Use an existing React 18 or 19 application with matching `react-dom`. The following local build
|
|
12
|
+
workflow needs Node.js 22 or newer:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm install @tileflow/react@alpha @tileflow/core@alpha @tileflow/maps@alpha "maplibre-gl@^6.4.1"
|
|
16
|
+
npm install --save-dev --save-exact tileflow@alpha
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The supported peer ranges are React/React DOM 18–19 and MapLibre GL JS `>=6.4.1 <7`. The worker
|
|
20
|
+
must come from the same MapLibre installation as the main module.
|
|
21
|
+
|
|
22
|
+
## Prepare a map
|
|
23
|
+
|
|
24
|
+
Create `tileflow.config.ts` at the application root:
|
|
25
|
+
|
|
26
|
+
<!-- docs:check -->
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import {defineMap} from '@tileflow/core';
|
|
30
|
+
import {streets} from '@tileflow/maps';
|
|
31
|
+
|
|
32
|
+
export default defineMap({
|
|
33
|
+
id: 'madrid',
|
|
34
|
+
version: 1,
|
|
35
|
+
extends: streets,
|
|
36
|
+
view: {center: [-3.7038, 40.4168], zoom: 12},
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Build the assets into the application's public directory:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
npx tileflow build --out public/tileflow
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
This assumes the application serves `public/` at its URL root. Rebuild after config or asset
|
|
47
|
+
changes, or use the [Vite](https://github.com/tileflow/tileflow-sdk/blob/main/packages/vite/README.md),
|
|
48
|
+
[Next.js](https://github.com/tileflow/tileflow-sdk/blob/main/packages/next/README.md), or
|
|
49
|
+
[Webpack](https://github.com/tileflow/tileflow-sdk/blob/main/packages/webpack/README.md) integration
|
|
50
|
+
for watched development and production builds. Do not use both workflows to overwrite the same
|
|
51
|
+
hosted manifest.
|
|
52
|
+
|
|
53
|
+
## Configure the worker
|
|
54
|
+
|
|
55
|
+
In a Vite application's client entry, add this before mounting React:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
|
|
59
|
+
import {configureTileflowMapLibre} from '@tileflow/react';
|
|
60
|
+
|
|
61
|
+
configureTileflowMapLibre({workerUrl});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This import syntax is specific to Vite. Use the Next.js or Webpack guide linked above for that
|
|
65
|
+
bundler's worker-delivery recipe. Configure the worker once, outside component rendering. Do not
|
|
66
|
+
use a CDN worker from another MapLibre version. Next.js interactive components belong behind a
|
|
67
|
+
`'use client'` boundary.
|
|
68
|
+
|
|
69
|
+
## Render a map
|
|
70
|
+
|
|
71
|
+
Import MapLibre's CSS once in the application. After the worker and assets are ready, render:
|
|
72
|
+
|
|
73
|
+
<!-- docs:check -->
|
|
6
74
|
|
|
7
75
|
```tsx
|
|
8
|
-
import {Map} from '@tileflow/react';
|
|
9
76
|
import 'maplibre-gl/dist/maplibre-gl.css';
|
|
77
|
+
import {Map} from '@tileflow/react';
|
|
10
78
|
|
|
11
79
|
export function App() {
|
|
12
80
|
return (
|
|
@@ -15,72 +83,69 @@ export function App() {
|
|
|
15
83
|
theme="system"
|
|
16
84
|
center={[-3.7038, 40.4168]}
|
|
17
85
|
zoom={12}
|
|
18
|
-
mapOptions={{
|
|
19
|
-
cooperativeGestures: true,
|
|
20
|
-
maxZoom: 18,
|
|
21
|
-
}}
|
|
86
|
+
mapOptions={{cooperativeGestures: true, maxZoom: 18}}
|
|
22
87
|
/>
|
|
23
88
|
);
|
|
24
89
|
}
|
|
25
90
|
```
|
|
26
91
|
|
|
27
|
-
|
|
92
|
+
Coordinates are `[longitude, latitude]`. `source.map` must match the config's portable map ID,
|
|
93
|
+
not a hosted `map_...` identifier. The default manifest URL is exactly `/tileflow/manifest.json`.
|
|
94
|
+
For a subpath or external host, provide `manifestUrl` in the source; the component does not infer
|
|
95
|
+
bundler configuration or search for assets.
|
|
28
96
|
|
|
29
|
-
|
|
30
|
-
|
|
97
|
+
`theme` selects a published concrete theme. Omission uses `defaultTheme`; `system` requires an
|
|
98
|
+
explicit light/dark mapping, which Streets supplies. Theme changes preserve the MapLibre instance,
|
|
99
|
+
camera, and interactions, and roll back on failure. `onThemeChange` reports transitions.
|
|
31
100
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
101
|
+
`mapOptions` accepts native MapLibre options except `container` and `style`. Direct camera props
|
|
102
|
+
take priority over `mapOptions`, then the manifest view, then shared defaults. To load one unmanaged
|
|
103
|
+
style, use `source={{kind: 'maplibre', style: styleUrl}}`; that source has no Tileflow theme switching
|
|
104
|
+
or manifest identity. Do not supply a Tileflow theme with an unmanaged source.
|
|
35
105
|
|
|
36
|
-
|
|
37
|
-
```
|
|
106
|
+
## Add annotations and popups
|
|
38
107
|
|
|
39
|
-
|
|
40
|
-
MapLibre-free. MapLibre GL JS 6.4.1-6.x is supported. Use the `@tileflow/next` or
|
|
41
|
-
`@tileflow/webpack` README for their worker-delivery recipes.
|
|
108
|
+
Install the contract package when importing its types directly:
|
|
42
109
|
|
|
43
|
-
|
|
110
|
+
```sh
|
|
111
|
+
npm install @tileflow/interactions@alpha
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Annotations are small, application-owned marker sets. Every annotation has a stable `id`, singular
|
|
115
|
+
`coordinate`, and non-empty `ariaLabel`. Data must be JSON-safe. Native React renderers use portals
|
|
116
|
+
into hosts managed by the interaction runtime:
|
|
44
117
|
|
|
45
|
-
|
|
46
|
-
`renderMarker`, `renderTooltip`, and `renderPopup` render native React UI through portals into the
|
|
47
|
-
MapLibre-owned marker and overlay hosts.
|
|
118
|
+
<!-- docs:check -->
|
|
48
119
|
|
|
49
120
|
```tsx
|
|
50
|
-
import {Map} from '@tileflow/react';
|
|
51
121
|
import {useState} from 'react';
|
|
52
122
|
import type {TileflowAnnotation, TileflowInteractionState} from '@tileflow/interactions';
|
|
123
|
+
import {Map} from '@tileflow/react';
|
|
53
124
|
|
|
54
|
-
type Property = {
|
|
55
|
-
price: number;
|
|
56
|
-
title: string;
|
|
57
|
-
};
|
|
125
|
+
type Property = {price: number; title: string};
|
|
58
126
|
|
|
59
127
|
const annotations = [
|
|
60
128
|
{
|
|
61
|
-
ariaLabel: 'Apartment in Madrid',
|
|
62
|
-
coordinate: [-3.7038, 40.4168],
|
|
63
|
-
data: {price: 320_000, title: 'Apartment in Madrid'},
|
|
64
129
|
id: 'property-42',
|
|
65
130
|
kind: 'marker',
|
|
66
|
-
|
|
131
|
+
coordinate: [-3.7038, 40.4168],
|
|
132
|
+
ariaLabel: 'Apartment in Madrid',
|
|
133
|
+
data: {price: 320_000, title: 'Apartment in Madrid'},
|
|
67
134
|
tooltip: {content: {kind: 'field', field: 'title'}},
|
|
68
135
|
popup: {content: {kind: 'view', name: 'property-card'}},
|
|
69
136
|
},
|
|
70
137
|
] satisfies readonly TileflowAnnotation<Property>[];
|
|
71
138
|
|
|
72
139
|
export function PropertyMap() {
|
|
73
|
-
const [
|
|
140
|
+
const [state, setState] = useState<TileflowInteractionState>({popup: null});
|
|
74
141
|
|
|
75
142
|
return (
|
|
76
143
|
<Map
|
|
77
144
|
source={{kind: 'tileflow', map: 'madrid'}}
|
|
78
145
|
annotations={annotations}
|
|
79
|
-
interactionState={
|
|
80
|
-
onInteractionStateChange={
|
|
81
|
-
onInteractionDiagnostic={(diagnostic) => console.error(diagnostic)}
|
|
82
|
-
onInteractionEvent={(event) => console.log(event.type, event.target)}
|
|
83
|
-
renderMarker={({annotation}) => <strong>EUR {annotation.data.price.toLocaleString()}</strong>}
|
|
146
|
+
interactionState={state}
|
|
147
|
+
onInteractionStateChange={setState}
|
|
148
|
+
onInteractionDiagnostic={(diagnostic) => console.error(diagnostic.code)}
|
|
84
149
|
renderPopup={({annotation, close}) => (
|
|
85
150
|
<article>
|
|
86
151
|
<h2>{annotation.data.title}</h2>
|
|
@@ -95,208 +160,107 @@ export function PropertyMap() {
|
|
|
95
160
|
}
|
|
96
161
|
```
|
|
97
162
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
host.
|
|
102
|
-
|
|
103
|
-
`renderMarker` is always annotation-only. Without `interactions`, `renderTooltip` and `renderPopup`
|
|
104
|
-
also infer the annotation-specific context, including typed `annotation.data`. When `interactions`
|
|
105
|
-
is present, they receive the common `TileflowInteractionViewContext`; narrow `context.target.kind`
|
|
106
|
-
(or check `annotation in context`) when one renderer serves both annotation and semantic targets.
|
|
107
|
-
|
|
108
|
-
## Semantic POI interactions
|
|
109
|
-
|
|
110
|
-
Use `interactions` to attach tooltip or popup behavior to POIs already rendered by a finalized
|
|
111
|
-
Tileflow style. Application code names the `poi` domain, never compiler-generated MapLibre layer
|
|
112
|
-
IDs. The runtime queries only manifest-declared layers and mounts DOM only for the active overlay.
|
|
113
|
-
|
|
114
|
-
```tsx
|
|
115
|
-
import {Map} from '@tileflow/react';
|
|
116
|
-
import type {TileflowInteractionBinding} from '@tileflow/interactions';
|
|
117
|
-
|
|
118
|
-
const interactions = [
|
|
119
|
-
{
|
|
120
|
-
id: 'poi-details',
|
|
121
|
-
target: {kind: 'semantic-feature', domain: 'poi', categories: ['food-drink', 'retail']},
|
|
122
|
-
tooltip: {content: {kind: 'field', field: 'name', fallback: 'Point of interest'}},
|
|
123
|
-
popup: {content: {kind: 'view', name: 'poi-card'}},
|
|
124
|
-
},
|
|
125
|
-
] satisfies readonly TileflowInteractionBinding[];
|
|
126
|
-
|
|
127
|
-
export function PoiMap() {
|
|
128
|
-
return (
|
|
129
|
-
<Map
|
|
130
|
-
source={{kind: 'tileflow', map: 'madrid'}}
|
|
131
|
-
interactions={interactions}
|
|
132
|
-
renderPopup={(context) =>
|
|
133
|
-
context.target.kind === 'semantic-feature' ? (
|
|
134
|
-
<article>
|
|
135
|
-
<h2>{String(context.target.feature.properties.name ?? 'Point of interest')}</h2>
|
|
136
|
-
<button type="button" onClick={context.close}>
|
|
137
|
-
Close
|
|
138
|
-
</button>
|
|
139
|
-
</article>
|
|
140
|
-
) : null
|
|
141
|
-
}
|
|
142
|
-
/>
|
|
143
|
-
);
|
|
144
|
-
}
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
Bindings and popup state are validated before reconciliation. An invalid replacement leaves the
|
|
148
|
-
last valid runtime state active and reports structured diagnostics. `interactionState` and
|
|
149
|
-
`defaultInteractionState` are mutually exclusive. Annotation and semantic overlays share one popup
|
|
150
|
-
state, so replacing either target closes the previous popup before opening the next.
|
|
151
|
-
|
|
152
|
-
`MapProps` rejects controlled and default interaction state together. Its `mode="image"` branch
|
|
153
|
-
excludes annotations, semantic bindings, interaction state, renderers, and interaction callbacks.
|
|
154
|
-
JavaScript callers and widened inputs still receive the corresponding runtime diagnostics.
|
|
163
|
+
This uses the worker/CSS setup from the preceding sections. Omit controlled `interactionState` and
|
|
164
|
+
use `defaultInteractionState` for uncontrolled state; never supply both or switch ownership during
|
|
165
|
+
the component's lifetime. Updating annotations, renderers, callbacks, or state does not recreate
|
|
166
|
+
the map. Reusing an annotation ID preserves a compatible marker host.
|
|
155
167
|
|
|
156
|
-
`
|
|
157
|
-
|
|
168
|
+
Use `interactions` with `target: {kind: 'semantic-feature', domain: 'poi'}` for POIs already in the
|
|
169
|
+
compiled map instead of creating a DOM marker for every feature. Optional categories use Tileflow's
|
|
170
|
+
semantic taxonomy, such as `food-drink` or `retail`, not raw source classes. The style must contain
|
|
171
|
+
compatible interaction metadata. With semantic bindings, narrow `context.target.kind` in
|
|
172
|
+
`renderTooltip` or `renderPopup` before accessing annotation or feature data. `renderMarker` remains
|
|
173
|
+
annotation-only. See the
|
|
174
|
+
[interaction guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/interactions/README.md).
|
|
158
175
|
|
|
159
|
-
|
|
160
|
-
|
|
176
|
+
Text/field content uses safe text defaults. A `view` is an application renderer name, not HTML.
|
|
177
|
+
Keep tooltips non-interactive; put buttons, links, and forms in popups.
|
|
161
178
|
|
|
162
|
-
|
|
163
|
-
defaults. A `view` descriptor is a dispatch name for an application renderer; it is not HTML or a
|
|
164
|
-
serialized component tree. Tooltip content remains non-interactive, while popup content may contain
|
|
165
|
-
normal React controls.
|
|
179
|
+
## Display an image or create a render
|
|
166
180
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
181
|
+
`<Map mode="image">` displays an existing explicit `imageUrl` or an image URL in the published
|
|
182
|
+
manifest. It does not create a static render, poll an operation, or load MapLibre. A local style
|
|
183
|
+
build alone does not create that image. Annotations, semantic bindings, and interaction state are
|
|
184
|
+
not supported in image mode.
|
|
171
185
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
Tileflow props such as `center`, `zoom`, and `interactive` take priority when
|
|
175
|
-
provided. Camera resolution is the same in interactive and image modes: direct props, then
|
|
176
|
-
`mapOptions`, then the published manifest view, then Tileflow's shared runtime defaults.
|
|
186
|
+
To request a new static render, use `StaticMap` from `@tileflow/react/static`. First install the
|
|
187
|
+
shared client/types used by this example:
|
|
177
188
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
object or URL: it deliberately has no Tileflow theme identity, `system` selection, switching, or
|
|
181
|
-
manifest traceability. Browser components do not compile `tileflow.config.ts`.
|
|
182
|
-
|
|
183
|
-
Without `manifestUrl`, the exact default is `/tileflow/manifest.json`. If Vite, Webpack, Next, a
|
|
184
|
-
reverse proxy, or the Tileflow plugin publishes it anywhere else, set the final public URL
|
|
185
|
-
explicitly; the component does not attempt runtime base-path discovery. Manifest 404s, unknown map
|
|
186
|
-
IDs, unresolved styles, and unresolved image URLs enter `data-tileflow-state="error"`.
|
|
187
|
-
|
|
188
|
-
`theme` selects a published theme name. Omitting it uses the map's `defaultTheme`; `"system"` is
|
|
189
|
-
available only when the map declares explicit light and dark mappings. Changes preload fonts, diff
|
|
190
|
-
the style on the existing MapLibre instance, preserve camera and interactions, and roll back if the
|
|
191
|
-
new style fails. `onThemeChange` reports preloading, applying, ready, and error transitions.
|
|
192
|
-
|
|
193
|
-
To reuse one published map across multiple repos, point every app at the same
|
|
194
|
-
manifest:
|
|
195
|
-
|
|
196
|
-
```tsx
|
|
197
|
-
<Map
|
|
198
|
-
source={{
|
|
199
|
-
kind: 'tileflow',
|
|
200
|
-
map: 'madrid',
|
|
201
|
-
manifestUrl: 'https://cdn.example.com/tileflow/manifest.json',
|
|
202
|
-
}}
|
|
203
|
-
/>
|
|
189
|
+
```sh
|
|
190
|
+
npm install @tileflow/static@alpha
|
|
204
191
|
```
|
|
205
192
|
|
|
206
|
-
|
|
193
|
+
The application must implement an authorized `/api/static-maps` endpoint that forwards the normalized
|
|
194
|
+
scene and idempotency key to the hosted service and returns its result contract. Keep privileged
|
|
195
|
+
Tileflow credentials on that server, not in React props or a browser bundle.
|
|
207
196
|
|
|
208
|
-
|
|
209
|
-
<Map
|
|
210
|
-
source={{
|
|
211
|
-
kind: 'maplibre',
|
|
212
|
-
style: 'https://cdn.example.com/tileflow/styles/madrid/dark.json',
|
|
213
|
-
}}
|
|
214
|
-
/>
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
For a lightweight display of an already hosted static image, use image mode:
|
|
197
|
+
<!-- docs:check -->
|
|
218
198
|
|
|
219
199
|
```tsx
|
|
220
|
-
<Map
|
|
221
|
-
source={{kind: 'tileflow', map: 'madrid'}}
|
|
222
|
-
mode="image"
|
|
223
|
-
center={[-3.7038, 40.4168]}
|
|
224
|
-
zoom={12}
|
|
225
|
-
/>
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
`Map mode="image"` only resolves an existing image URL (explicitly or from the published map
|
|
229
|
-
manifest) and renders an `<img>`; it does not submit a render scene, create an operation, poll, or
|
|
230
|
-
apply `StaticMap` overlays. This path does not load or evaluate MapLibre. Without an explicit
|
|
231
|
-
`imageUrl`, all environments use the image URL published for the Tileflow source.
|
|
232
|
-
|
|
233
|
-
For a new, fully specified render with exact size, center/bounds camera, overlays, idempotency, and
|
|
234
|
-
asynchronous create/poll behavior, use `StaticMap` from `@tileflow/react/static` or helpers from
|
|
235
|
-
`@tileflow/static`.
|
|
236
|
-
|
|
237
|
-
```tsx
|
|
238
|
-
import {StaticMap} from '@tileflow/react/static';
|
|
239
200
|
import {useState} from 'react';
|
|
240
|
-
import {
|
|
201
|
+
import {StaticMap} from '@tileflow/react/static';
|
|
202
|
+
import type {StaticMapAttributionEntry} from '@tileflow/static';
|
|
241
203
|
|
|
242
|
-
export function
|
|
243
|
-
const [
|
|
204
|
+
export function StaticPreview({idempotencyKey}: {idempotencyKey: string}) {
|
|
205
|
+
const [entries, setEntries] = useState<readonly StaticMapAttributionEntry[]>([]);
|
|
244
206
|
|
|
245
207
|
return (
|
|
246
|
-
<
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
208
|
+
<figure>
|
|
209
|
+
<StaticMap
|
|
210
|
+
map="madrid"
|
|
211
|
+
theme="dark"
|
|
212
|
+
alt="Map of central Madrid"
|
|
213
|
+
camera={{type: 'center', center: [-3.7038, 40.4168], zoom: 12}}
|
|
214
|
+
size={{width: 1200, height: 800}}
|
|
215
|
+
attribution={{mode: 'external'}}
|
|
216
|
+
createUrl="/api/static-maps"
|
|
217
|
+
idempotencyKey={idempotencyKey}
|
|
218
|
+
onReady={(result) => {
|
|
219
|
+
if ('attribution' in result) setEntries(result.attribution.entries);
|
|
220
|
+
}}
|
|
221
|
+
/>
|
|
222
|
+
<figcaption>
|
|
223
|
+
{entries.map((entry, index) => (
|
|
224
|
+
<p key={index}>
|
|
225
|
+
{entry.text}{' '}
|
|
226
|
+
{entry.links.map((link) => (
|
|
227
|
+
<a key={link.url} href={link.url}>
|
|
228
|
+
{link.label}
|
|
229
|
+
</a>
|
|
230
|
+
))}
|
|
231
|
+
</p>
|
|
232
|
+
))}
|
|
233
|
+
</figcaption>
|
|
234
|
+
</figure>
|
|
257
235
|
);
|
|
258
236
|
}
|
|
259
237
|
```
|
|
260
238
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
The root element exposes `data-tileflow-map`, optional `data-tileflow-capture-id`, and
|
|
290
|
-
`data-tileflow-state="loading|idle|error"`. Interactive mode becomes idle after MapLibre is idle
|
|
291
|
-
and two animation frames; style/data work returns it to loading. Image mode waits for decode or a
|
|
292
|
-
successful load fallback, including cached hydration. `tileflow capture` uses these markers for
|
|
293
|
-
application scenes and requires exactly one target.
|
|
294
|
-
|
|
295
|
-
## Compatibility
|
|
296
|
-
|
|
297
|
-
The supported peer window is React 18-19 and MapLibre GL JS 6.4.1-6.x. Compatibility smoke tests
|
|
298
|
-
install the exact lower bound and the selected current release from packed Tileflow tarballs,
|
|
299
|
-
typecheck a consumer, and render the image/SSR path while rejecting any MapLibre import. Future
|
|
300
|
-
majors stay outside the peer range until that matrix passes.
|
|
301
|
-
|
|
302
|
-
Docs: https://tileflow.dev/docs
|
|
239
|
+
Create the key with `createStaticMapIdempotencyKey()` once per intentional render action and retain
|
|
240
|
+
it in the owning application state across retries and remounts. Pass it into this component; do not
|
|
241
|
+
regenerate it on every render. A new scene is a new action and needs a new key.
|
|
242
|
+
|
|
243
|
+
Hosted results have `resultVersion: 1` and attribution. `onReady` also supports existing-image
|
|
244
|
+
results, which have no attribution field; narrow the union before reading it. External attribution
|
|
245
|
+
must remain visible beside the image. Omitted attribution uses embedded automatic placement.
|
|
246
|
+
See the [Static Maps guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/static/README.md)
|
|
247
|
+
for server transport, errors, overlays, and limits.
|
|
248
|
+
|
|
249
|
+
## Capture, authorization, and errors
|
|
250
|
+
|
|
251
|
+
`captureId` disambiguates repeated maps on a page. The root exposes `data-tileflow-map`, the resolved
|
|
252
|
+
`data-tileflow-theme`, optional `data-tileflow-capture-id`, and `data-tileflow-state="loading|idle|error"`.
|
|
253
|
+
Capture waits for MapLibre/image readiness and committed custom interaction views. Manifest 404s,
|
|
254
|
+
unknown maps/themes, and missing styles or images enter the error state rather than silently using
|
|
255
|
+
another map.
|
|
256
|
+
|
|
257
|
+
Hosted interactive maps acquire a short-lived session grant before eligible resource requests.
|
|
258
|
+
`analytics={{enabled: false}}` disables the optional beacon, not hosted authorization. A stable
|
|
259
|
+
`surfaceId`, such as `store-locator`, identifies a product location; do not use user IDs or URLs.
|
|
260
|
+
Existing request transforms remain application-owned, and direct World use can display an
|
|
261
|
+
owner-action notice when managed delivery is required.
|
|
262
|
+
|
|
263
|
+
The image/SSR path does not load MapLibre. Interactive rendering needs a browser with WebGL and the
|
|
264
|
+
matching worker assets. For release-specific APIs, use the installed declarations and README;
|
|
265
|
+
source `main` may be ahead of npm. Report defects in the
|
|
266
|
+
[issue tracker](https://github.com/tileflow/tileflow-sdk/issues).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tileflow/react",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.25",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"description": "React components for rendering Tileflow maps with MapLibre.",
|
|
6
6
|
"type": "module",
|
|
@@ -43,9 +43,9 @@
|
|
|
43
43
|
"access": "public"
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"@tileflow/core": ">=0.1.0-alpha.
|
|
47
|
-
"@tileflow/interactions": ">=0.1.0-alpha.
|
|
48
|
-
"@tileflow/static": ">=0.1.0-alpha.
|
|
46
|
+
"@tileflow/core": ">=0.1.0-alpha.25 <0.1.0-beta.0",
|
|
47
|
+
"@tileflow/interactions": ">=0.1.0-alpha.4 <0.1.0-beta.0",
|
|
48
|
+
"@tileflow/static": ">=0.1.0-alpha.26 <0.1.0-beta.0"
|
|
49
49
|
},
|
|
50
50
|
"peerDependencies": {
|
|
51
51
|
"maplibre-gl": ">=6.4.1 <7",
|