@tileflow/core 0.1.0-alpha.30 → 0.1.0-alpha.31

package/docs/authoring-model.md

@@ -173,6 +173,21 @@ const numericIdentity = expr.abs(expr.toNumber(expr.id(), 0));
 const decorativeBucket = expr.modulo(numericIdentity, 7);
 ```
 
+`expr.featureState(name)` reads a value an application sets on one feature at runtime, such as a
+selection or a hover. `expr.globalState(name)` reads a value an application sets once for the whole
+style with MapLibre's `map.setGlobalStateProperty(name, value)`, such as whether anything is
+selected. Both read `null` until set, so wrap them in a typed assertion with a fallback. MapLibre
+applies a global-state change to paint properties at once, without the style's paint transition.
+
+<!-- docs:check -->
+
+```ts
+import {expr} from '@tileflow/core';
+
+const selecting = expr.toBoolean(expr.globalState('selection'), false);
+const captionInk = expr.case([{when: selecting, value: '#1f2a44'}], '#ffffff');
+```
+
 The `land` module exposes stable land-use targets for `cemetery`, `civic`, `commercial`,
 `education`, `government`, `industrial`, `medical`, `military`, `parking`, `railway`,
 `recreation`, and `residential`. Its land-cover taxonomy distinguishes physical cover from authored

package/docs/map-emphasis.md

@@ -0,0 +1,89 @@
+# Map emphasis
+
+Start with the [@tileflow/core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for installation and a complete first example.
+
+An application that draws its own content over a Tileflow map, such as a route, a selected place, or
+search results, often needs the map to step back so that content reads first. Map emphasis does
+that on the map's own MapLibre instance: chosen modules recede towards the map's ground colour, and
+the map's labels and icons fade, except inside an area the application keeps at full strength. The
+change eases in and out, stays when the theme changes, and follows a theme blend.
+
+Emphasis needs a browser document and MapLibre GL JS. It changes only the layers a Tileflow map
+compiled, so an application's own layers, such as the route it draws, keep their appearance.
+
+## Show an emphasis
+
+Create the theme controller for the map, then ask for an emphasis. This example assumes an existing
+MapLibre map named `map` that shows the `dark` theme of a published Tileflow map, and a route the
+application has already drawn:
+
+```ts
+import type {Map as MapLibreMap} from 'maplibre-gl';
+import {createTileflowThemeController} from '@tileflow/core/browser';
+
+export function focusOnRoute(map: MapLibreMap, styleUrl: string) {
+  const controller = createTileflowThemeController({
+    initial: {style: styleUrl, theme: 'dark'},
+    map,
+  });
+  void controller.setEmphasis(
+    {
+      labels: 0.6,
+      recede: {boundaries: 0.55, roads: 0.5, transit: 0.5},
+    },
+    {transition: {duration: 560}},
+  );
+  return () => controller.setEmphasis(undefined, {transition: {duration: 560}});
+}
+```
+
+Roads, transit, and boundaries move halfway or a little more towards the ground colour, labels and
+icons keep 60 % of their opacity, and the change eases in over 560 milliseconds. Calling
+`setEmphasis(undefined)` eases the map back to its design. Each call supersedes the previous one;
+the promise of a superseded call resolves with `status: 'superseded'`.
+
+## Choose what steps back
+
+- `recede` maps module names to an amount from 0 (as designed) to 1 (the ground colour itself). The
+  modules are the semantic domains a map compiles, such as `roads`, `transit`, `boundaries`,
+  `water`, `land`, `buildings`, and `vegetation`. Every colour of a receding layer moves towards the
+  ground colour, including the colours inside zoom curves and data cases. Artwork that cannot be
+  recoloured, such as a pattern, fades by the same amount instead.
+- `labels` is the share of their opacity that the map's labels and icons keep, from 0 to 1.
+- `keep` is a GeoJSON `Polygon` or `MultiPolygon`. Labels and icons whose features fall inside it
+  keep their full strength. It can hold up to 4,096 positions. A corridor round a route is a
+  typical keep area.
+
+The ground colour is the map's background colour. During a blend it is the blended background, so
+receding colours follow the hour as the blend moves.
+
+## How it changes over time
+
+Values that depend only on the camera, such as a colour or an opacity with a zoom curve, ease every
+frame. A value that MapLibre evaluates per feature, such as a road colour chosen by class or any
+label opacity once a keep area is given, would make MapLibre lay its source out again on every
+change. Such values change once, at the start of the change, under a snapshot of the map that fades
+out as the transition runs. When the browser asks for reduced motion, every change happens at once.
+
+An emphasis stays through `setTheme` and `setBlend`: after a new style is applied, the emphasis is
+written again under the same cross-fade, and each blend position recomputes the receded colours.
+
+## How it finds modules
+
+Every compiled layer names its semantic module in its metadata:
+
+```json
+{"id": "tileflow-road-major-fill", "metadata": {"tileflow:domain": "roads"}}
+```
+
+Layers that a theme blend splits or copies keep the same entry. Applications can read the key from
+`tileflowLayerDomainMetadataKey` in `@tileflow/core/browser`. Physical layer IDs remain diagnostic;
+use the module name instead. Styles compiled before this metadata existed have no module names, so
+an emphasis leaves them unchanged.
+
+## Cost
+
+Each eased frame writes only the values that changed, with `setPaintProperty` and without
+validation. For a detailed city map with roads, transit, and boundaries receding, that is about 150
+values a frame on a desktop computer. Writing values directly is faster than reading a MapLibre
+global state from every value, because a global state change re-evaluates every layer that reads it.

package/docs/theme-transitions-and-blends.md

@@ -8,8 +8,9 @@ blend when the application controls the appearance continuously, such as a slide
 passes from night to day.
 
 Both work on the one MapLibre map the application already has. They create no second map, add no
-map views, and request the same tiles as a map that does not change theme. They need a browser
-document and MapLibre GL JS; the React Native package does not offer them.
+map views, and request the same tiles as a map that does not change theme. The React, Vue, and
+Svelte maps offer them with MapLibre GL JS, and the React Native map with MapLibre Native on iOS
+and Android; see [React Native](#react-native) for what differs there.
 
 ## Cross-fade a theme change
 
@@ -117,6 +118,48 @@ For a detailed city map this takes a few milliseconds on a mid-range phone. Posi
 four-hundredth of a theme are not applied, so a slowly moving position leaves the map at rest
 between changes.
 
+## React Native
+
+The `Map` of `@tileflow/react-native` accepts the same `themeTransition` and `themeBlend` props:
+
+```tsx
+import {Map} from '@tileflow/react-native';
+
+export function DayMap({position}: {position: number}) {
+  return (
+    <Map
+      source={{map: 'city', manifestUrl: 'https://maps.example.com/tileflow/manifest.json'}}
+      themeTransition={{duration: 450}}
+      themeBlend={{position, themes: ['night', 'dusk', 'day']}}
+      style={{flex: 1}}
+    />
+  );
+}
+```
+
+A transition covers the drawn map with a snapshot of its current frame, below markers and map
+controls. The snapshot follows the camera and fades out once the new style is drawn.
+`onReadinessChange` and `onThemeChange` report `ready` after the fade. The device's reduce-motion
+setting (iOS) or removed animations (Android) change at once.
+
+A blend loads every blended theme's style once and replaces the map's style once. Position changes
+then apply in batches on the main thread, at most one at a time, and later positions replace any
+that are still waiting. MapLibre Native's style transition smooths values between batches.
+
+What follows the position differs from the browser in a few ways:
+
+- Ground colours and numbers, pattern artwork, and light follow the position. Native maps have no
+  sky.
+- Labels, icons, and switched values change at the nearest theme under a short cross-fade of the
+  whole map. Icon artwork changes by image name instead of mixing pixels, so stretchable images
+  keep their stretch and content areas.
+- A value that depends on feature data and cannot be split by class, such as a road casing chosen
+  by access and zoom together, is drawn once per theme. Only the nearest theme's copy is shown.
+  The map has a few more layers while the blend is shown.
+
+If the application's native build predates these props, for example after an over-the-air
+JavaScript update, themes change at once and a blend shows its nearest theme.
+
 ## Use the core controller
 
 Framework adapters use `createTileflowThemeController` from `@tileflow/core/browser`. A direct
@@ -124,12 +167,12 @@ MapLibre integration can use it too. Resolve runtime styles from the published m
 `resolveTileflowRuntimeStyle` and `resolveTileflowRuntimeThemeBlend` from `@tileflow/core/runtime`:
 
 ```ts
+import type {Map as MapLibreMap} from 'maplibre-gl';
 import {createTileflowThemeController} from '@tileflow/core/browser';
 import {
   resolveTileflowRuntimeStyle,
   resolveTileflowRuntimeThemeBlend,
 } from '@tileflow/core/runtime';
-import type {Map as MapLibreMap} from 'maplibre-gl';
 import type {TileflowRuntimeManifestMap} from '@tileflow/core/runtime';
 
 export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowRuntimeManifestMap) {
@@ -163,3 +206,16 @@ latest wins. A failed change restores the previous appearance and reports `faile
 The controller loads blended themes' style documents with the same request policy it uses for
 style font metadata: same-origin credentials, no redirects, and a bounded size. Pass `loadStyle`
 when styles need another loader.
+
+The controller also shows [map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md),
+which stays through theme changes and follows every blend position.
+
+## Fast sweeps on slower devices
+
+Each position change makes MapLibre evaluate the paint of every layer whose value changed. A clock
+that moves slowly changes few values per frame, and positions closer than a four-hundredth of a
+theme are skipped. A sweep that crosses a whole theme in a few seconds while the camera also moves
+changes most ground layers on every frame. Measured in Chromium on Apple silicon at 1440 × 900 for
+a detailed city map, such a sweep kept 76 frames a second; with the processor slowed four times, as
+on a mid-range phone, it fell to about 11, against 28 for the same camera move without the sweep.
+On slower devices, prefer short sweeps or move the position less often.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",