@fieldia/map 0.0.0-stage → 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fieldia-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @fieldia/map
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Fieldia](https://fieldia.dev)'s maps: a **place** and an **area** as fields of a
+form, on the map provider you choose. Built on [Leaflet](https://leafletjs.com),
+loaded only when a map is shown.
+
+```sh
+npm install @fieldia/map
+```
+
+```ts
+import { mountViewer } from '@fieldia/viewer';
+import { mapWidgets, azureMaps } from '@fieldia/map';
+
+mountViewer(host, {
+  page,
+  dataSource,
+  widgets: mapWidgets({
+    provider: azureMaps({ token: () => fetch('/maps/token').then((r) => r.text()) }),
+    center: { lat: 30.0444, lng: 31.2357 },
+  }),
+});
+```
+
+## Place
+
+A point on a form: a press on the map, a dragged pin, an address found, typed
+coordinates, or "My location". On a `json` field it is kept as a GeoJSON Point;
+on a `float` field it keeps the latitude, with `longitudeField` naming the field
+for the longitude.
+
+```json
+{ "type": "field", "id": "deliver_to", "field": "deliver_to", "widget": "place",
+  "options": { "addressField": "street", "zoom": 17 } }
+```
+
+Options: `longitudeField`, `addressField` (filled from the address found, or
+named from the point where the provider can, never over what a person typed),
+`myLocation` and `search` (on unless `false`), `zoom`, `height`.
+
+## Area
+
+A polygon, a box or a circle, kept in a `json` field as a GeoJSON Feature whose
+`properties.shape` says how it was drawn (a circle is its centre and
+`properties.radius` in metres). Its points, corners and edge drag to change it,
+the whole area drags to move it, and a point between two adds one.
+
+```json
+{ "type": "field", "id": "zone", "field": "zone", "widget": "area",
+  "options": { "shapes": ["polygon", "box"], "areas": [{ "label": "Downtown", "value": { "type": "Polygon", "coordinates": [[[31.235, 30.04], [31.25, 30.04], [31.25, 30.055], [31.235, 30.04]]] } }] } }
+```
+
+Options: `shapes` (any of polygon, box, circle), `areas` (named areas to choose
+instead of drawing), `height`.
+
+## Without a mouse
+
+Tab reaches the map, which shows a cross at its centre: the arrow keys move the
+map, plus and minus zoom. On a place, Enter puts the place at the cross and the
+arrow keys move the pin. On an area, Space puts a point at the cross, Enter
+finishes, Backspace takes a point back, Escape stops; a grip moves with the
+arrow keys and leaves with Delete. A scroll passes over a map to the page
+unless Ctrl (⌘) is held, and on a phone one finger scrolls the page while two
+move the map.
+
+## Providers
+
+| Provider | Road | Dark | Satellite | Address search |
+| --- | --- | --- | --- | --- |
+| `azureMaps({ key })` or `({ token, clientId })` | yes | yes | yes | yes, as people type |
+| `googleMaps({ key, region, logo })` (Map Tiles API) | yes | no | yes | the app's own (`search`) |
+| `mapbox({ token })` | yes | yes | yes | yes, as people type |
+| `tiles({ url, credit })` | the app's own map images | | | the app's own |
+| `openStreetMap()` | yes, **for demos only** | no | no | Photon, as people type, nearest first (or `{ search: 'nominatim' }`, on Enter) |
+
+Keys never live in Fieldia: pass one restricted to your sites, or a function
+fetching a short-lived token from your server. Each provider's credits are shown
+in the map's corner, and its mark where its terms ask. Read your provider's
+terms on keeping search results: a place field keeps what it finds (Mapbox's
+permanent geocoding is asked for by default). OpenStreetMap's public map images,
+Photon's public server and Nominatim are for trying things out: their policies
+treat an app in use as heavy use. Photon can run on your own server
+(`openStreetMap({ photonUrl })`).
+
+Suggestions come as people type where the provider allows it, nearest where the
+map is looking first, each on two lines (the place, then where it is); Enter
+takes the first. "My location" says how sure it is: a rough location (a
+desktop's, placed by its network) shows the circle it may be anywhere in, says
+how wide, and names no address from it.
+
+Pass your own `search` (and `reverse`) to `mapWidgets` to use your own address
+search with any provider.
+
+## In the designer
+
+`mapKinds({ locale })` gives the designer Place and Area for its toolbox, with
+their settings; pass the map widgets to the designer and its editors too.
+
+MIT. Leaflet is BSD-2-Clause; its stylesheet is included with its licence.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@fieldia/map",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.14.1",
+  "description": "Fieldia's maps: a place and an area as fields, on any map provider. Leaflet, loaded only where a map is shown.",
+  "license": "MIT",
+  "homepage": "https://fieldia.dev",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "module": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./src/index.d.mts",
+        "require": "./src/index.d.ts"
+      },
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@fieldia/core": "0.14.1",
+    "@fieldia/widgets": "0.14.1",
+    "leaflet": "^1.9.4",
+    "tslib": "^2.8.1"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fieldia-dev/fieldia",
+    "directory": "libs/map"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/src/index.d.mts

@@ -0,0 +1,6 @@
+export { mapWidgets } from './lib/widgets.mjs';
+export { mapKinds, type MapKind, type MapKindContext } from './lib/kinds.mjs';
+export type { MapSettings } from './lib/settings.mjs';
+export { azureMaps, googleMaps, mapbox, openStreetMap, tiles, type AddressSearch, type AzureMapsOptions, type BaseMap, type Credit, type GoogleMapsOptions, type MapboxOptions, type MapProvider, type MapView, type OpenStreetMapOptions, type PlaceFound, type ReverseSearch, type SearchRequest, type TileSpec, type TilesOptions, } from './lib/providers.mjs';
+export { readArea, readPoint, writeArea, writePoint, metresBetween, type Area, type AreaFeature, type LatLng, type PointGeometry, type Shape } from './lib/geo.mjs';
+export { MAP_LABELS, type MapLabels } from './lib/labels.mjs';

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export { mapWidgets } from './lib/widgets';
+export { mapKinds, type MapKind, type MapKindContext } from './lib/kinds';
+export type { MapSettings } from './lib/settings';
+export { azureMaps, googleMaps, mapbox, openStreetMap, tiles, type AddressSearch, type AzureMapsOptions, type BaseMap, type Credit, type GoogleMapsOptions, type MapboxOptions, type MapProvider, type MapView, type OpenStreetMapOptions, type PlaceFound, type ReverseSearch, type SearchRequest, type TileSpec, type TilesOptions, } from './lib/providers';
+export { readArea, readPoint, writeArea, writePoint, metresBetween, type Area, type AreaFeature, type LatLng, type PointGeometry, type Shape } from './lib/geo';
+export { MAP_LABELS, type MapLabels } from './lib/labels';

package/src/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAP_LABELS = exports.metresBetween = exports.writePoint = exports.writeArea = exports.readPoint = exports.readArea = exports.tiles = exports.openStreetMap = exports.mapbox = exports.googleMaps = exports.azureMaps = exports.mapKinds = exports.mapWidgets = void 0;
+var widgets_1 = require("./lib/widgets");
+Object.defineProperty(exports, "mapWidgets", { enumerable: true, get: function () { return widgets_1.mapWidgets; } });
+var kinds_1 = require("./lib/kinds");
+Object.defineProperty(exports, "mapKinds", { enumerable: true, get: function () { return kinds_1.mapKinds; } });
+var providers_1 = require("./lib/providers");
+Object.defineProperty(exports, "azureMaps", { enumerable: true, get: function () { return providers_1.azureMaps; } });
+Object.defineProperty(exports, "googleMaps", { enumerable: true, get: function () { return providers_1.googleMaps; } });
+Object.defineProperty(exports, "mapbox", { enumerable: true, get: function () { return providers_1.mapbox; } });
+Object.defineProperty(exports, "openStreetMap", { enumerable: true, get: function () { return providers_1.openStreetMap; } });
+Object.defineProperty(exports, "tiles", { enumerable: true, get: function () { return providers_1.tiles; } });
+var geo_1 = require("./lib/geo");
+Object.defineProperty(exports, "readArea", { enumerable: true, get: function () { return geo_1.readArea; } });
+Object.defineProperty(exports, "readPoint", { enumerable: true, get: function () { return geo_1.readPoint; } });
+Object.defineProperty(exports, "writeArea", { enumerable: true, get: function () { return geo_1.writeArea; } });
+Object.defineProperty(exports, "writePoint", { enumerable: true, get: function () { return geo_1.writePoint; } });
+Object.defineProperty(exports, "metresBetween", { enumerable: true, get: function () { return geo_1.metresBetween; } });
+var labels_1 = require("./lib/labels");
+Object.defineProperty(exports, "MAP_LABELS", { enumerable: true, get: function () { return labels_1.MAP_LABELS; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/map/src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA2C;AAAlC,qGAAA,UAAU,OAAA;AACnB,qCAA0E;AAAjE,iGAAA,QAAQ,OAAA;AAEjB,6CAoByB;AAnBvB,sGAAA,SAAS,OAAA;AACT,uGAAA,UAAU,OAAA;AACV,mGAAA,MAAM,OAAA;AACN,0GAAA,aAAa,OAAA;AACb,kGAAA,KAAK,OAAA;AAgBP,iCAAgK;AAAvJ,+FAAA,QAAQ,OAAA;AAAE,gGAAA,SAAS,OAAA;AAAE,gGAAA,SAAS,OAAA;AAAE,iGAAA,UAAU,OAAA;AAAE,oGAAA,aAAa,OAAA;AAClE,uCAA0D;AAAjD,oGAAA,UAAU,OAAA"}

package/src/index.mjs

@@ -0,0 +1,6 @@
+export { mapWidgets } from './lib/widgets.mjs';
+export { mapKinds } from './lib/kinds.mjs';
+export { azureMaps, googleMaps, mapbox, openStreetMap, tiles, } from './lib/providers.mjs';
+export { readArea, readPoint, writeArea, writePoint, metresBetween } from './lib/geo.mjs';
+export { MAP_LABELS } from './lib/labels.mjs';
+//# sourceMappingURL=index.mjs.map

package/src/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../../libs/map/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAqC,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACb,KAAK,GAeN,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAA4E,MAAM,WAAW,CAAC;AAChK,OAAO,EAAE,UAAU,EAAkB,MAAM,cAAc,CAAC"}

package/src/lib/area.d.mts

@@ -0,0 +1,3 @@
+import type { WidgetFactory } from '@fieldia/widgets';
+import type { MapSettings } from './settings.mjs';
+export declare function areaWidget(settings: MapSettings): WidgetFactory;

package/src/lib/area.d.ts

@@ -0,0 +1,3 @@
+import type { WidgetFactory } from '@fieldia/widgets';
+import type { MapSettings } from './settings';
+export declare function areaWidget(settings: MapSettings): WidgetFactory;