@tileflow/interactions 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -1,4 +1,4 @@
-# `@tileflow/interactions`
+# @tileflow/interactions
 
 Portable annotations, tooltips, popups, state, and interaction bindings for Tileflow maps.
 
@@ -10,10 +10,26 @@ The package has two boundaries:
 Framework applications normally use `@tileflow/react`, `@tileflow/vue`, or `@tileflow/svelte`
 instead of calling the MapLibre controller directly.
 
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+```sh
+npm install @tileflow/interactions@alpha
+```
+
+The root entry needs no MapLibre installation or browser. For live UI, install one framework adapter
+and follow its worker, CSS, and asset-preparation guide:
+[React](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react/README.md),
+[Vue](https://github.com/tileflow/tileflow-sdk/blob/main/packages/vue/README.md), or
+[Svelte](https://github.com/tileflow/tileflow-sdk/blob/main/packages/svelte/README.md).
+
 ## Annotation model
 
+<!-- docs:check -->
+
 ```ts
-import type {TileflowAnnotation} from '@tileflow/interactions';
+import {type TileflowAnnotation, validateTileflowAnnotations} from '@tileflow/interactions';
 
 const properties = [
   {
@@ -27,6 +43,10 @@ const properties = [
     popup: {content: {kind: 'view', name: 'property-card'}},
   },
 ] satisfies TileflowAnnotation[];
+
+const result = validateTileflowAnnotations(properties);
+if (!result.ok) throw new Error(JSON.stringify(result.diagnostics));
+console.log(result.annotations);
 ```
 
 `text` and scalar `field` content are inserted as text. `view` is a small dispatch name for a
@@ -35,11 +55,13 @@ Custom tooltip views must remain brief and non-focusable; put buttons, links, fo
 interactive content in a popup.
 
 Every new annotation needs a stable `id`, singular `coordinate`, and non-empty `ariaLabel`.
-Optional `data` must be recursively JSON-safe. Call `validateTileflowAnnotations` at an untrusted
+Coordinates use `[longitude, latitude]`. Optional `data` must be recursively JSON-safe. Call `validateTileflowAnnotations` at an untrusted
 boundary to receive atomic validation and structured JSON-Pointer diagnostics.
 
 ## Popup state
 
+<!-- docs:check -->
+
 ```ts
 import {
   initialTileflowInteractionState,
@@ -59,6 +81,8 @@ adapters expose controlled and uncontrolled ownership without changing this seri
 
 The first semantic runtime target is `domain: 'poi'`:
 
+<!-- docs:check -->
+
 ```ts
 import type {TileflowInteractionBinding} from '@tileflow/interactions';
 
@@ -91,5 +115,5 @@ objects and schedulers are injected at attach time, so both subpath imports rema
 `createTileflowMapLibreInteractionCoordinator` joins them around one controlled or uncontrolled
 popup state and commits the closing runtime before the opening runtime.
 
-See [`docs/contracts/map-interactions.md`](../../docs/contracts/map-interactions.md) for lifecycle,
+See [`docs/contracts/map-interactions.md`](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/map-interactions.md) for lifecycle,
 accessibility, security, capture, and framework parity requirements.

package/dist/maplibre-entry.js

@@ -1662,7 +1662,7 @@ var tileflowInteractionActionSchema = z.discriminatedUnion("type", [
 
 // src/maplibre-poi.ts
 var interactionManifestMetadataKey = "tileflow:interaction-manifest";
-var interactionManifestVersion = 2;
+var interactionManifestVersion = 3;
 var missingSourceLayerNamespace = "
tileflow-no-source-layer";
 function createTileflowMapLibrePoiController(options) {
   let bindings = semanticPoiBindings(options.bindings ?? [], options.onDiagnostic);
@@ -1726,9 +1726,20 @@ function createTileflowMapLibrePoiController(options) {
         );
         continue;
       }
+      const properties = normalizePoiProperties(feature.properties, manifest.fields);
+      const category = properties.category;
+      if (category === void 0) {
+        manifestMismatch = true;
+        diagnostic(
+          options.onDiagnostic,
+          "SEMANTIC_MANIFEST_MISMATCH",
+          "A rendered POI feature has no supported category."
+        );
+        continue;
+      }
       const binding = bindings.find((candidate) => {
         const target = candidate.target;
-        return target.kind === "semantic-feature" && target.domain === "poi" && (!target.categories || target.categories.includes(layer.category));
+        return target.kind === "semantic-feature" && target.domain === "poi" && (!target.categories || target.categories.includes(category));
       });
       if (!binding) continue;
       const featureId = normalizeFeatureId(feature.id);
@@ -1742,9 +1753,9 @@ function createTileflowMapLibrePoiController(options) {
             coordinate: [event.lngLat.lng, event.lngLat.lat],
             domain: "poi",
             feature: {
-              category: layer.category,
+              category,
               ...featureId === void 0 ? {} : { id: featureId },
-              properties: normalizePoiProperties(feature.properties, manifest.fields)
+              properties
             },
             kind: "semantic-feature"
           }
@@ -1974,7 +1985,7 @@ function parsePoiManifest(styleInput, onDiagnostic) {
   for (const input of layerInputs) {
     const layer = asRecord(input);
     const sourceLayer = layer?.sourceLayer;
-    if (!layer || !isTileflowPoiCategory(layer.category) || !isSafeManifestName(layer.layerId) || !isSafeManifestName(layer.source) || sourceLayer !== void 0 && !isSafeManifestName(sourceLayer) || layer.anchor !== "pointer-coordinate" || !isPoiRepresentation(layer.representation) || !Number.isSafeInteger(layer.priority) || layer.priority < 0 || layer.priority > 1e5 || ids.has(layer.layerId)) {
+    if (!layer || !isSafeManifestName(layer.layerId) || !isSafeManifestName(layer.source) || sourceLayer !== void 0 && !isSafeManifestName(sourceLayer) || layer.anchor !== "pointer-coordinate" || !isPoiRepresentation(layer.representation) || !Number.isSafeInteger(layer.priority) || layer.priority < 0 || layer.priority > 1e5 || ids.has(layer.layerId)) {
       diagnostic(onDiagnostic, "SEMANTIC_MANIFEST_MISMATCH", "Invalid semantic POI layer lookup.");
       return null;
     }
@@ -2002,7 +2013,6 @@ function parsePoiManifest(styleInput, onDiagnostic) {
     identityNamespace = namespace;
     ids.add(layer.layerId);
     layers.push({
-      category: layer.category,
       layerId: layer.layerId,
       priority: layer.priority,
       representation: layer.representation,
@@ -2072,11 +2082,7 @@ function sourceLayerNamespace(sourceLayer) {
   return sourceLayer ?? missingSourceLayerNamespace;
 }
 function relevantLayerIds(manifest, bindings) {
-  return manifest.layers.filter(
-    (layer) => bindings.some(
-      (binding) => binding.target.kind === "semantic-feature" && (!binding.target.categories || binding.target.categories.includes(layer.category))
-    )
-  ).map((layer) => layer.layerId);
+  return bindings.some((binding) => binding.target.kind === "semantic-feature") ? manifest.layers.map((layer) => layer.layerId) : [];
 }
 function normalizePoiProperties(properties, fields) {
   const source = properties ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/interactions",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "license": "Apache-2.0",
   "description": "Portable annotation and interaction contracts for Tileflow maps.",
   "type": "module",