@tileflow/dom 0.0.0-bootstrap.0 → 0.1.0-alpha.0

package/README.md

@@ -1,7 +1,111 @@
 # @tileflow/dom
 
-This bootstrap package registers the npm name for Trusted Publishing. It contains no runtime or
-dependencies and is not an application SDK. Do not use it in an application.
+Mount an interactive Tileflow map in any DOM element, without a framework. One function creates
+the map, loads its manifest and style, keeps its theme, colours, camera, annotations and
+interactions current, and takes everything down again. It draws nothing of its own around the map:
+marker, popup and tooltip views, loading and error states belong to your page.
 
-Once the first runtime alpha is available, install `@tileflow/dom@alpha` and follow its
-packaged README. This version is reserved for package registration, not the alpha channel.
+Use it for plain pages and web components. The React, Vue and Svelte packages are the easier way in
+those frameworks.
+
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+Supported peers are MapLibre GL JS `>=6.4.1 <7`. The local build workflow below requires
+Node.js 22 or newer.
+
+```sh
+npm install @tileflow/dom@alpha @tileflow/core@alpha @tileflow/maps@alpha "maplibre-gl@^6.4.1"
+npm install --save-dev --save-exact tileflow@alpha
+```
+
+Build a map into `public/tileflow` with `npx tileflow build --out public/tileflow`, as the
+[React guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react/README.md#prepare-a-map)
+shows.
+
+With Vite, the plugin from `@tileflow/vite` gives every map MapLibre's worker, in development and
+in production builds, so the application configures nothing. `tileflow()` prepares maps and adds
+the worker. When the CLI build or a hosted manifest provides the maps, add only the worker
+(`npm install --save-dev @tileflow/vite@alpha`):
+
+```ts
+import {defineConfig} from 'vite';
+import {tileflowMapLibreWorker} from '@tileflow/vite';
+
+export default defineConfig({plugins: [tileflowMapLibreWorker()]});
+```
+
+The worker comes from the same installed MapLibre as the map's main module.
+
+With another bundler, configure the worker once before the first map, with the URL at which the
+page serves `maplibre-gl/dist/maplibre-gl-worker.mjs`. An explicit configuration wins over the
+Vite plugin's:
+
+```ts
+import {configureTileflowMapLibre} from '@tileflow/dom';
+
+configureTileflowMapLibre({workerUrl: '/assets/maplibre-gl-worker.mjs'});
+```
+
+## Mount a map
+
+The container needs a size; the map fills it and follows its resizes.
+
+<!-- docs:check -->
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+import {createTileflowMap} from '@tileflow/dom';
+
+const container = document.querySelector<HTMLElement>('#map')!;
+const map = createTileflowMap(container, {
+  source: {map: 'madrid'},
+  theme: 'system',
+  annotations: [
+    {
+      ariaLabel: 'Prado Museum',
+      coordinate: [-3.6921, 40.4138],
+      id: 'prado',
+      kind: 'marker',
+      popup: {content: {kind: 'view', name: 'museum'}},
+    },
+  ],
+  views: {
+    popup(element, {close}) {
+      const button = document.createElement('button');
+      button.textContent = 'Close';
+      button.addEventListener('click', close);
+      element.append(button);
+    },
+  },
+  onError: ({code, error}) => console.warn(code, error),
+});
+
+await map.ready;
+map.setTheme('dark');
+map.setColors({water: 'var(--brand)'});
+map.destroy();
+```
+
+`createTileflowMap` returns at once. `ready` settles with the MapLibre map when it first loads.
+Each setter applies one option; `update` applies several and does no work for values that did not
+change, so an adapter can hand over all of its props on every render. The container carries
+`data-tileflow-state` (`loading`, `idle` or `error`) for capture, and `getStatus` with
+`onStatusChange` give the same readiness, the theme shown and interaction diagnostics to your own
+loading or error view.
+
+A view renderer fills the element it receives. It runs again on an emptied element when its context
+changes, unless it returns `update`; `destroy` runs when the view leaves the map. A marker view
+receives hover, focus and whether its popup is open in `state`.
+
+`mode: "image"` shows a static image of the map instead, without loading MapLibre; `ready` then
+settles with `null` once the image has loaded.
+
+See [REFERENCE.md](REFERENCE.md) for every option and controller method.
+
+## Next steps
+
+- [Show a popup on click](https://tileflow.dev/docs/examples/show-a-popup-on-click)
+- [Themes and tokens](https://tileflow.dev/docs/map-design/themes-and-tokens)
+- [Capture a map](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/README.md)

package/REFERENCE.md

@@ -0,0 +1,80 @@
+# @tileflow/dom reference
+
+## `createTileflowMap(container, options, createOptions?)`
+
+Mounts a map in `container` and returns a controller at once. MapLibre loads lazily, after the
+manifest and style are ready. Throws a `TypeError` for an invalid `source`, `theme`, `timeOfDay`,
+`themeBlend` or `themeTransition`, and when both `views` and `renderTargets` are given.
+
+### Options
+
+Every option except `source` is optional and can change after mount through `update` or a setter.
+
+| Option                                           | Meaning                                                                                                   |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `source`                                         | `{map, manifestUrl?}`: the map by name, from the default manifest or `manifestUrl`.                       |
+| `theme`, `timeOfDay`                             | A concrete theme or `"system"`, which follows the page's colour scheme; an optional artistic preset.      |
+| `themeBlend`                                     | `{themes, position, hold?}`: a continuous blend of two to eight themes instead of `theme`.                |
+| `themeTransition`                                | `{duration}` in milliseconds, used for theme, blend, colour and emphasis changes.                         |
+| `colors`, `emphasis`                             | Colour token or knob overrides (CSS variables are read where the map sits); modules that recede.          |
+| `vegetation`, `viewMode`                         | 3D scene inputs; `viewMode` defaults to `"3d"`.                                                           |
+| `center`, `zoom`                                 | The view until `bounds` or `fitAnnotations` is given; a change moves the camera at once.                  |
+| `bounds`, `fitBoundsOptions`, `fitAnnotations`   | Bounds to show, how they are fitted, or a fit to all annotations. The first fit is immediate.             |
+| `interactive`, `navigationControl`               | Whether the map takes input; zoom and compass buttons, none unless asked.                                 |
+| `mapOptions`                                     | MapLibre options apart from `container` and `style`. A structurally different value recreates the map.    |
+| `analytics`                                      | Analytics fields merged with the style's own.                                                             |
+| `annotations`, `annotationClusters`              | Portable annotations and optional clustering.                                                             |
+| `dataSources`, `dataOverlays`                    | Application GeoJSON and the overlays drawn over it, keyed as in `defineMap`.                              |
+| `interactions`                                   | Semantic interaction bindings on map features.                                                            |
+| `interactionState` or `defaultInteractionState`  | The open popup, controlled or initial. Which of the two is used is fixed when the map is created.         |
+| `views`                                          | `{marker?, popup?, tooltip?}` renderers that fill a plain element.                                        |
+| `renderTargets`                                  | `{marker?, popup?, tooltip?, onChange}` for a framework that draws views itself; replaces `views`.        |
+| `onLoad`, `onError`, `onThemeChange`             | The loaded MapLibre map; `{code, error}` failures (`console.error` without a handler); theme transitions. |
+| `onInteractionEvent`, `onInteractionStateChange` | Pointer and popup events; requested popup state.                                                          |
+| `onInteractionDiagnostic`                        | Each distinct interaction diagnostic, once.                                                               |
+| `onStatusChange`                                 | Every change to the status `getStatus` returns.                                                           |
+| `mode`, `imageUrl`, `alt`, `imageLoading`        | `"image"` shows a static image instead of a map: `imageUrl`, or one the map's style resolves.             |
+| `image`                                          | In image mode, an `<img>` your page renders (or `null` until it does); otherwise the map adds its own.    |
+
+### Image mode
+
+With `mode: "image"` no MapLibre loads. The map shows `imageUrl`, or an image of the style at the
+view and container size, and is `idle` once that image has loaded and decoded. Annotations,
+interactions, interaction state, interaction callbacks and views are unavailable there and report
+`UNSUPPORTED_MODE`. A framework that renders on the server passes its own `<img>` as `image` and
+sets its `src` from `status.imageUrl`.
+
+### Create options
+
+Read once: `captureId` (written as `data-tileflow-capture-id`), `sessionSource` (names the
+integration in session analytics) and `statusElement` (the element that receives the capture
+attributes; the container unless given, none when `null`).
+
+### Views
+
+A renderer is `(element, context) => void | {update?, destroy?}`. It runs when the view appears,
+and again on an emptied element when its context changes, unless it returned `update`. `destroy`
+runs when the view leaves the map. A marker context has `state: {hovered, focused, selected}`;
+popup and tooltip contexts belong to an annotation or to a map feature and carry `close`. A kind
+with no renderer keeps the default view.
+
+## Controller
+
+| Member                                                   | Meaning                                                                                                                                            |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`                                                  | Settles with the MapLibre map on its first load (`null` once an image shows); rejects when it cannot start or is destroyed first.                  |
+| `update(options)`                                        | Applies changed options; left-out keys keep their value, `undefined` clears one.                                                                   |
+| `setTheme`, `setThemeBlend`, `setColors`, `setEmphasis`  | One option each.                                                                                                                                   |
+| `setView({center, zoom})`, `setBounds(bounds, options?)` | Camera options.                                                                                                                                    |
+| `setAnnotations`, `setInteractions`, `setViews`          | Content options.                                                                                                                                   |
+| `setInteractionState(state)`                             | Opens or closes a popup; on a controlled map the same as passing `interactionState`.                                                               |
+| `getStatus()`                                            | `{readiness, theme, diagnostics, imageUrl}`: `loading`, `idle` or `error`, the theme shown, interaction diagnostics and, in image mode, the image. |
+| `getMap()`, `getThemeController()`                       | The MapLibre map and theme controller, `null` until the map exists and after it is taken down.                                                     |
+| `getInteractionState()`, `getRenderTargets()`            | The open popup; the view elements the map handed out.                                                                                              |
+| `destroy()`                                              | Takes the map down, removes the capture attributes and stops every listener. Later calls do nothing.                                               |
+
+## `getTileflowMapInitialStatus(options, controlledInteractionState?)`
+
+The status a map with these options has before it mounts: its declarative diagnostics, `error` or
+`loading`, the theme it names and, in image mode, `imageUrl`. It touches no DOM, so a framework can
+render capture attributes on the server and before the controller exists.

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import * as maplibre_gl from 'maplibre-gl';
+import { Map, MapOptions } from 'maplibre-gl';
+import { TileflowMapLibreOverlay, TileflowGeoJsonSource } from '@tileflow/core';
+import { TileflowThemeController, TileflowBounds, TileflowFitBoundsOptions, TileflowColorOverrides, TileflowEmphasis, TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowNavigationControlInput, TileflowMapError, TileflowThemeTransition } from '@tileflow/core/browser';
+import { TileflowThemeSelection, TileflowRuntimeSource, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
+import { TileflowAnnotation, TileflowAnnotationViewContext, TileflowInteractionViewContext, TileflowInteractionState, TileflowInteractionDiagnostic, TileflowInteractionBinding, TileflowInteractionEvent } from '@tileflow/interactions';
+import { TileflowMapLibreDomRenderTarget, TileflowMapLibreSemanticDomRenderTarget, TileflowAnnotationClusterOptions } from '@tileflow/interactions/maplibre';
+
+/**
+ * What a view renderer may return: `update` receives the next context instead of the view being
+ * rendered again from an empty element, and `destroy` runs when the view leaves the map.
+ */
+type TileflowMapViewInstance<TContext> = Readonly<{
+    destroy?: () => void;
+    update?: (context: TContext) => void;
+}>;
+/**
+ * Fills `element` with a view. It runs when the view appears and again, on an emptied element,
+ * whenever its context changes, unless it returned an `update`.
+ */
+type TileflowMapViewRenderer<TContext> = (element: HTMLElement, context: TContext) => TileflowMapViewInstance<TContext> | void;
+/** Views drawn into marker, popup and tooltip elements. Each kind left out keeps the default view. */
+type TileflowMapViews<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    marker?: TileflowMapViewRenderer<TileflowAnnotationViewContext<TAnnotation>>;
+    popup?: TileflowMapViewRenderer<TileflowInteractionViewContext<TAnnotation>>;
+    tooltip?: TileflowMapViewRenderer<TileflowInteractionViewContext<TAnnotation>>;
+}>;
+type TileflowMapRenderTargetList<TAnnotation extends TileflowAnnotation> = Readonly<{
+    annotations: readonly TileflowMapLibreDomRenderTarget<TAnnotation>[];
+    semantic: readonly TileflowMapLibreSemanticDomRenderTarget[];
+}>;
+
+/** MapLibre options a map passes through, apart from the container and style it owns. */
+type TileflowMapLibreOptions = Omit<MapOptions, 'container' | 'style'>;
+type TileflowMapReadiness = 'error' | 'idle' | 'loading';
+/**
+ * Where the map stands, for capture and for an application's own loading or error view. The map
+ * draws nothing for it: `diagnostics` are for the application to show.
+ */
+type TileflowMapStatus = Readonly<{
+    /** Interaction problems: invalid annotations, interactions or state, and runtime failures. */
+    diagnostics: readonly TileflowInteractionDiagnostic[];
+    /** `idle` once the map, its theme and its views have settled; `error` when one cannot. */
+    readiness: TileflowMapReadiness;
+    /** The concrete theme shown, once it is known. */
+    theme: string | undefined;
+    /** In image mode, the image to show, once it is known. */
+    imageUrl: string | undefined;
+}>;
+/**
+ * For a framework that draws views itself, such as through portals: the map leaves the elements of
+ * the kinds marked `true` empty and hands every element to `onChange`.
+ */
+type TileflowMapRenderTargetsOptions<TAnnotation extends TileflowAnnotation> = Readonly<{
+    marker?: boolean;
+    onChange: (targets: TileflowMapRenderTargetList<TAnnotation>) => void;
+    popup?: boolean;
+    tooltip?: boolean;
+}>;
+type TileflowMapInteractionStateOptions = Readonly<{
+    defaultInteractionState?: never;
+    interactionState?: TileflowInteractionState;
+}> | Readonly<{
+    defaultInteractionState?: TileflowInteractionState;
+    interactionState?: never;
+}>;
+type TileflowMapControllerOptions<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = TileflowMapInteractionStateOptions & {
+    /** The map to show, by name, from the manifest at `manifestUrl` or the default one. */
+    source: TileflowRuntimeSource;
+    /**
+     * `image` shows a static image of the map instead of MapLibre: `imageUrl`, or one the map's
+     * static renderer makes for the container's size, `center`, `zoom` and theme.
+     */
+    mode?: 'image' | 'interactive';
+    imageUrl?: string;
+    /** The image's alternative text; empty unless given. */
+    alt?: string;
+    /** How the browser loads the image; `eager` unless given. */
+    imageLoading?: 'eager' | 'lazy';
+    /**
+     * The `<img>` a framework renders itself (with `imageUrl` from the status), so the image can be
+     * rendered on the server. Without it, the map adds its own image to the container.
+     */
+    image?: HTMLImageElement | null;
+    theme?: TileflowThemeSelection;
+    /** Optional artistic preset; ignored by maps without this capability. */
+    timeOfDay?: TileflowTimeOfDay;
+    /** Shows a continuous blend of the map's themes instead of `theme`. */
+    themeBlend?: TileflowBrowserThemeBlendSelection;
+    /** Cross-fades theme, blend, colour and emphasis changes. */
+    themeTransition?: TileflowThemeTransitionOptions;
+    /** Colour token or knob overrides, which may use CSS variables read where the map sits. */
+    colors?: TileflowColorOverrides;
+    /** Makes chosen modules of the map recede so the application's content reads first. */
+    emphasis?: TileflowEmphasis;
+    vegetation?: boolean;
+    viewMode?: TileflowViewMode;
+    center?: [number, number];
+    zoom?: number;
+    /** Shows these bounds; `center` and `zoom` set the view only until bounds are given. */
+    bounds?: TileflowBounds;
+    /** Fits the map to all annotations, and again whenever their positions change. */
+    fitAnnotations?: boolean | TileflowFitBoundsOptions;
+    fitBoundsOptions?: TileflowFitBoundsOptions;
+    interactive?: boolean;
+    /** Zoom and compass buttons; none unless asked. */
+    navigationControl?: TileflowNavigationControlInput;
+    mapOptions?: TileflowMapLibreOptions;
+    analytics?: TileflowAnalytics;
+    /** Group `annotations` into accessible cluster buttons. Up to 1,000 annotations. */
+    annotationClusters?: TileflowAnnotationClusterOptions;
+    annotations?: readonly TAnnotation[];
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreOverlay>>;
+    dataSources?: Readonly<Record<string, TileflowGeoJsonSource>>;
+    interactions?: readonly TileflowInteractionBinding[];
+    /** Views drawn into marker, popup and tooltip elements. */
+    views?: TileflowMapViews<TAnnotation>;
+    /** Hands view elements to a framework that draws them; replaces `views`. */
+    renderTargets?: TileflowMapRenderTargetsOptions<TAnnotation>;
+    onError?: (event: TileflowMapError) => void;
+    onLoad?: (map: Map) => void;
+    onThemeChange?: (transition: TileflowThemeTransition) => void;
+    onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onInteractionEvent?: (event: TileflowInteractionEvent<TAnnotation>) => void;
+    onInteractionStateChange?: (state: TileflowInteractionState) => void;
+    onStatusChange?: (status: TileflowMapStatus) => void;
+};
+/** Options read once, when the map is created. */
+type TileflowMapCreateOptions = Readonly<{
+    /** Names the map in deterministic capture, as `data-tileflow-capture-id`. */
+    captureId?: string;
+    /** Names the integration in session analytics; adapters pass their framework. */
+    sessionSource?: string;
+    /**
+     * Receives `data-tileflow-map`, `data-tileflow-theme`, `data-tileflow-state` and
+     * `data-tileflow-capture-id`; the container unless given, none when `null`.
+     */
+    statusElement?: HTMLElement | null;
+}>;
+type TileflowMapController<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    container: HTMLElement;
+    /**
+     * Settles with the MapLibre map when it first loads, or with `null` once an image-mode map has
+     * shown its image; rejects when it cannot start or when the controller is destroyed first.
+     */
+    ready: Promise<Map | null>;
+    /** Takes the map down, empties what it added to the container, and stops every listener. */
+    destroy(): void;
+    getInteractionState(): TileflowInteractionState;
+    /** The MapLibre map, or `null` before it is created and after it is taken down. */
+    getMap(): Map | null;
+    getRenderTargets(): TileflowMapRenderTargetList<TAnnotation>;
+    getStatus(): TileflowMapStatus;
+    /** Changes theme, colours and emphasis; `null` until the map exists or when it has no themes. */
+    getThemeController(): TileflowThemeController | null;
+    setAnnotations(annotations: readonly TAnnotation[] | undefined): void;
+    setBounds(bounds: TileflowBounds | undefined, options?: TileflowFitBoundsOptions): void;
+    setColors(colors: TileflowColorOverrides | undefined): void;
+    setEmphasis(emphasis: TileflowEmphasis | undefined): void;
+    setInteractions(interactions: readonly TileflowInteractionBinding[] | undefined): void;
+    /** Opens or closes a popup; on a controlled map it is the same as passing `interactionState`. */
+    setInteractionState(state: TileflowInteractionState): void;
+    setTheme(theme: TileflowThemeSelection | undefined): void;
+    setThemeBlend(themeBlend: TileflowBrowserThemeBlendSelection | undefined): void;
+    setView(view: Readonly<{
+        center?: [number, number];
+        zoom?: number;
+    }>): void;
+    setViews(views: TileflowMapViews<TAnnotation> | undefined): void;
+    /**
+     * Applies changed options. Keys left out keep their value; a key given as `undefined` clears it.
+     * Unchanged values do no work, so an adapter can pass all of its props on every render.
+     */
+    update(options: Partial<TileflowMapControllerOptions<TAnnotation>>): void;
+}>;
+/**
+ * Mounts a Tileflow map in `container` and returns its controller. The container should have a
+ * size; the map fills it and follows its resizes. Nothing is drawn around the map: loading,
+ * error and diagnostic views belong to the application, from `getStatus` and `onStatusChange`.
+ */
+declare function createTileflowMap<TAnnotation extends TileflowAnnotation = TileflowAnnotation>(container: HTMLElement, initialOptions: TileflowMapControllerOptions<TAnnotation>, createOptions?: TileflowMapCreateOptions): TileflowMapController<TAnnotation>;
+/**
+ * The status a map with these options has before it mounts: for server rendering and a framework's
+ * first render, so the page shows the same theme, diagnostics and image before and after mount.
+ * `controlledInteractionOwnership` is whether the map started with `interactionState`.
+ */
+declare function getTileflowMapInitialStatus<TAnnotation extends TileflowAnnotation = TileflowAnnotation>(options: TileflowMapControllerOptions<TAnnotation>, controlledInteractionOwnership?: boolean): TileflowMapStatus;
+
+type TileflowMapLibre = typeof maplibre_gl;
+type TileflowMapLibreConfiguration = Readonly<{
+    workerUrl: string;
+}>;
+/** Configure the application-owned worker before mounting an interactive Tileflow map. */
+declare function configureTileflowMapLibre(configuration: TileflowMapLibreConfiguration): void;
+/** Load the interactive renderer only after a browser map requests it. */
+declare function loadTileflowMapLibre(): Promise<TileflowMapLibre>;
+
+export { type TileflowMapController, type TileflowMapControllerOptions, type TileflowMapCreateOptions, type TileflowMapLibre, type TileflowMapLibreConfiguration, type TileflowMapLibreOptions, type TileflowMapReadiness, type TileflowMapRenderTargetList, type TileflowMapRenderTargetsOptions, type TileflowMapStatus, type TileflowMapViewInstance, type TileflowMapViewRenderer, type TileflowMapViews, configureTileflowMapLibre, createTileflowMap, getTileflowMapInitialStatus, loadTileflowMapLibre };