@object-ui/plugin-map 17.6.0 → 18.0.0

package/README.md

@@ -7,13 +7,22 @@ marker comes from a record's own coordinate fields, and the first paint frames t
 records that were fetched. It is a *view over data* — there is no authored marker
 list, and no pin you place by hand.
 
-Importing the package registers two component types on the `ComponentRegistry`,
-both resolving to the same renderer:
+Importing the package registers one component type on the `ComponentRegistry`:
+`object-map`, the object-bound renderer. Inside an `ObjectView`, a stored `map`
+view is compiled to an `object-map` node, so a saved map view ends at the same
+component.
 
-- `object-map` — the object-bound renderer
-- `map` — the bare spec view-type name (`ViewTypeSchema`'s `'map'`), for a node
-  authored with it directly. Inside an `ObjectView`, a `map` view is compiled to
-  an `object-map` node, so both spellings end at the same component.
+> **The bare `map` node type key is retired** (objectui#10393, following the
+> objectui#8008 ruling that retired `gantt`). The registry used to accept a node
+> authored `"type": "map"` (and its namespaced twin `view:map`) while the
+> published declaration refused it — `ObjectMapSchema.type` is the literal
+> `'object-map'` and no schema arm names `map` — so a validated document could not
+> use the key the registry took. Write `"type": "object-map"`.
+>
+> ⚠️ The **stored view type** `"map"` — what a saved `listViews[].type` or
+> `defaultViewType` holds — is a **different layer and is unchanged**. Do not
+> rewrite it: `ObjectView` maps a stored `map` view onto the `object-map` node
+> type, so no saved view moves.
 
 ## Installation
 
@@ -50,18 +59,28 @@ consumer is the missing input.
 Registration is a side effect of the import. There is no manual-registration
 export to iterate over — the import *is* the registration.
 
+An authored `object-map` node takes its props in its `properties` bag, whose
+members are `@objectstack/spec`'s `ComponentPropsMap['object-map']` row.
+`objectui validate` refuses a prop written flat on the node by name, naming its
+bag member, as the spec's own page component does (objectui#10859).
+`SchemaRenderer` hoists the bag onto the node before `ObjectMap` runs, so
+`ObjectMapSchema` (`@object-ui/types`) is the node as the component reads it.
+
 ```ts
 import '@object-ui/plugin-map';
+import type { ObjectMapBlockNode } from '@object-ui/types';
 
 // Object-bound: the markers are the records the query returns.
-const schema = {
+const schema: ObjectMapBlockNode = {
   type: 'object-map',
-  objectName: 'stores',
-  map: {
-    latitudeField: 'lat',
-    longitudeField: 'lng',
-    titleField: 'name',
-    descriptionField: 'address',
+  properties: {
+    objectName: 'stores',
+    map: {
+      latitudeField: 'lat',
+      longitudeField: 'lng',
+      titleField: 'name',
+      descriptionField: 'address',
+    },
   },
 };
 ```
@@ -69,41 +88,94 @@ const schema = {
 A literal record array instead of a query, with the same `map` block:
 
 ```ts
-const schema = {
+import type { ObjectMapBlockNode } from '@object-ui/types';
+
+const schema: ObjectMapBlockNode = {
   type: 'object-map',
-  staticData: [
-    { id: 1, name: 'San Francisco HQ', lat: 37.7749, lng: -122.4194 },
-    { id: 2, name: 'Oakland Office', lat: 37.8044, lng: -122.2711 },
-  ],
-  map: { latitudeField: 'lat', longitudeField: 'lng', titleField: 'name' },
+  properties: {
+    staticData: [
+      { id: 1, name: 'San Francisco HQ', lat: 37.7749, lng: -122.4194 },
+      { id: 2, name: 'Oakland Office', lat: 37.8044, lng: -122.2711 },
+    ],
+    map: { latitudeField: 'lat', longitudeField: 'lng', titleField: 'name' },
+  },
 };
 ```
 
 `filter` and `sort` are the **query's** filter and order — they reach the data
 source as `$filter` / `$orderby`, and the spec's per-element `dataSource` binding
-is honoured as well. The map issues no row cap of its own.
+is honoured as well.
+
+**The provider does not change which query keys apply** (objectui#9061, the port
+of objectui#8769). An authored `filter` and `sort` narrow and order the rows on
+**every** provider, inline ones included — `staticData` and
+`data: { provider: 'value', items }` both reach the same in-memory adapter the
+other providers go through, so `filter` is evaluated with the same matcher. A
+bare array under `data` is not a record source on this map (objectui#8348): the
+ladder falls through to `staticData`, then `objectName`, so inline rows belong
+under `staticData`. Before objectui#9061 the inline provider skipped that query
+and plotted every authored row with an authored `filter` silently dropped. The
+platform row ceiling (2,000 drawn rows, with a footnote naming both numbers — objectui#7210,
+ruling a′) applies to inline rows too, and it is applied to the **filtered** set,
+never to the raw one: a large inline array that a `filter` cuts below the ceiling
+plots every matching row and shows no footnote.
+
+⚠️ Two consequences of routing inline rows through the adapter. They reach the
+map as that adapter's own deep copy rather than as the authored array's object
+identities, so code comparing a record handed to `onMarkerClick` against the
+authored array with `===` needs `id` equality instead; and the copy is a JSON
+round-trip, so inline rows must be JSON-serializable.
 
 ## The `map` block
 
-The declared configuration input. Every key is optional:
+The declared configuration input. Every key is optional, and the block is
+**closed** (objectui#5157): a key outside this table — a typo such as
+`latitudeFieId` — is refused by `objectui validate` with an `unrecognized_keys`
+issue at `properties.map` that names it (on a root node; a nested node reports under
+`invalid_union` at `children`, with the key in the arm detail). At runtime
+`ObjectMap` does not throw: it renders from the declared keys and warns
+`[ObjectMap] Invalid map configuration` in the console, naming the same key; the
+undeclared key is never read. A typo that leaves the block with no coordinate
+binding, as `latitudeFieId` does, therefore draws the "Map configuration
+required" refusal below rather than a map.
 
 | Key | Description |
 | --- | --- |
 | `latitudeField` | Record field holding the latitude. Needs `longitudeField` alongside it; both values must be numbers. |
 | `longitudeField` | Record field holding the longitude. |
 | `locationField` | Single field holding both coordinates — see the formats below. Used when the lat/lng pair yields nothing. |
-| `titleField` | Field shown as the marker title. Omitted, markers are titled `Marker`. |
+| `titleField` | Field shown as the marker title. Omitted, the title is resolved by the object's own record-title precedence (`@object-ui/core`'s `getRecordDisplayName`, ADR-0079): the declared `nameField`, its deprecated `displayNameField` alias, the legacy `titleFormat` template, a type-aware pick from the object's fields, then name-ish keys read straight off the record — the rung that answers when no object definition reached the view, as `staticData` and an inline `data: { provider: 'value', items }` configuration never fetch one. `Record #<id>` is the floor; `Marker` is reached only by a record carrying no id at all. |
 | `descriptionField` | Field shown under the title in the marker popup. |
 | `zoom` | Zoom level. Declaring it opts this view out of the auto-fit (see below). |
 | `center` | `[latitude, longitude]` — a two-number **tuple**, latitude first. Declaring it opts this view out of the auto-fit. |
-| `style` | MapLibre style URL/spec, replacing the default public demo style. |
+| `style` | MapLibre style URL/spec, replacing the default public demo style. The node-level `mapStyle` is read before it, so it applies when `mapStyle` is absent. |
+
+**Nothing is guessed — an unbound map REFUSES.** A map with no coordinate binding
+renders
+
+> Map configuration required — declare `map.locationField` or `map.latitudeField` + `map.longitudeField`
+
+in place of the map, rather than painting an empty one (objectui#8169, ruled
+2026-09-07). *Unbound* is a property of the resolved config, not of the spelling
+that produced it — an absent `map` block, a block naming only `titleField`, and a
+`latitudeField` with no `longitudeField` beside it all refuse alike.
+
+The four field-name defaults this component used to fall back to — `latitude` /
+`longitude` / `location` / `description` — are gone, and so are the
+`locationField: … || 'location'` floors that `plugin-list` and `plugin-view` used
+to add on the way in. ⚠️ **Behaviour change for existing metadata**: a record set
+that happens to carry `latitude` / `longitude` columns no longer plots on a view
+that declared no binding — it refuses, and the fix is to declare the binding.
+A title field is still never guessed (objectui#5953): an unconfigured marker
+takes its title from the record-title precedence above.
 
-**The block replaces the field-name defaults, it is not merged with them.** With
-no map configuration at all the component falls back to the field names
-`latitude` / `longitude` / `location` / `name` / `description`; the moment a `map`
-block is present, only what it declares is read. So `map: { titleField: 'name' }`
-on its own names no coordinate field, places nothing, and renders an empty map
-under the excluded-records notice — the defaults do not fill the gap.
+## Node-level keys beside the block
+
+| Key | Description |
+| --- | --- |
+| `mapStyle` | MapLibre style URL or spec, replacing the demo tiles. Read before `map.style`, so it wins when both are written. Not the node's base `style`, which is an inline CSS record. |
+| `enableClustering` | `true` groups nearby markers into numbered clusters. Absent, the map clusters only above 100 markers; `false` turns clustering off at any count. |
+| `navigation` | What a marker click opens — the spec's `NavigationConfig`. `drawer`, `modal` and `popover` open the marker's record; `new_window` (or `openNewTab: true`, which outranks every mode except `none`) opens the record page in a new tab; `preventNavigation: true` opens nothing. An absent key, `none` and `split` open nothing (the map hands the split shell no main panel). `page`, and a block without `mode` (the spec's `page` default), open the record page of the map's `objectName` through the record navigator the host publishes (the console publishes one on its custom pages, record pages and list views); under a host that publishes none, or on a map that names no `objectName`, the click opens nothing. A parent view's click handler outranks the whole key. |
 
 ## Initial camera
 
@@ -128,17 +200,25 @@ and it does not cost the view its fit.
 
 ## Coordinate formats
 
-`locationField` reads any of:
+`locationField` names one record field, and the value in it is read at RUNTIME:
+`extractCoordinates()` in `packages/plugin-map/src/ObjectMap.tsx` tests the value's
+shape per record and takes the first of these three that answers. So this is a
+reference read of what that parser accepts, not a value you author — which is why
+it is a table rather than a snippet:
 
-```ts
-{ location: { lat: 37.7749, lng: -122.4194 } }  // also latitude/longitude, lon
-{ location: '37.7749,-122.4194' }               // "lat,lng"
-{ location: [37.7749, -122.4194] }              // [lat, lng]
-```
+| Shape of `record[locationField]` | Example value | What the parser accepts |
+| --- | --- | --- |
+| Object | `{ lat: 37.7749, lng: -122.4194 }` | `lat` or `latitude` for the latitude; `lng`, `lon` or `longitude` for the longitude. Both must already be numbers — an object form is not string-parsed. |
+| String | `'37.7749,-122.4194'` | `"lat,lng"`: split on the comma, each half trimmed and `parseFloat`-ed. |
+| Array | `[37.7749, -122.4194]` | `[lat, lng]`, exactly two elements, each `parseFloat`-ed. |
+
+The lat/lng PAIR (`latitudeField` + `longitudeField`) is tried first and is
+stricter: both values must already be numbers, with no parsing step at all.
 
 A record whose coordinates are missing, unparseable, or out of range (latitude
 beyond ±90, longitude beyond ±180) is left off the map and counted in a notice
-above it, rather than being silently dropped or rescued.
+above it, rather than being silently dropped or rescued. The range test and the
+notice live in that same file, alongside the parser.
 
 ## What this component does not read
 
@@ -154,10 +234,14 @@ console.
 
 `ObjectMap` (the component), `ObjectMapRenderer` (the registered wrapper, for a
 host that registers types itself) and the `ObjectMapProps` type are the package's
-exports:
+exports. A component mounted directly is not behind `SchemaRenderer`, so nothing
+hoists a `properties` bag: its `schema` prop takes the node as the component
+reads it, with the keys flat:
 
 ```tsx
-import { ObjectMap } from '@object-ui/plugin-map';
+import { ObjectMap, type ObjectMapProps } from '@object-ui/plugin-map';
+
+declare const dataSource: ObjectMapProps['dataSource'];
 
 <ObjectMap
   schema={{ type: 'object-map', objectName: 'stores', map: { latitudeField: 'lat', longitudeField: 'lng' } }}
@@ -169,7 +253,7 @@ import { ObjectMap } from '@object-ui/plugin-map';
 | Prop | Description |
 | --- | --- |
 | `schema` | The map schema — the keys above. |
-| `dataSource` | Resolves the `object` provider. Not needed for `staticData` or an inline `data` array. |
+| `dataSource` | Resolves the `object` provider. Not needed for `staticData` or an inline `data: { provider: 'value', items }` configuration. |
 | `className` | Classes for the wrapper around the map. |
 | `data` | Records to render directly, bypassing the component's own fetch — the shape `ListView` passes when it already holds the rows. Tracked live: passing a new array after mount (e.g. once a host's own in-flight query resolves) updates the map. |
 | `onMarkerClick` | Called with the clicked record. |

package/dist/ObjectMap.d.ts

@@ -14,7 +14,21 @@ export interface ObjectMapProps {
      */
     data?: any[];
     onMarkerClick?: (record: any) => void;
-    onRowClick?: (record: any) => void;
+    /**
+     * TWO parameters since objectui#9357, and the second is not decoration: this
+     * prop reaches `useNavigationOverlay` as its `onRowClick`, and `handleClick`
+     * invokes it as `onRowClick(record, event)` — the modifier payload a host
+     * needs to implement Cmd/Ctrl/middle-click for itself. Declaring one
+     * parameter hid the second on the ONE line a host reads. Spelled `any` and
+     * not `HandleClickModifiers` for the reason objectui#9341 measured on
+     * `ObjectKanbanSchema.onCardClick`: that interface lives in
+     * `@object-ui/react`, the published twins in `@object-ui/types` may not name
+     * it, and a host that discovered the payload from the implementation
+     * annotated it `React.MouseEvent` — which a narrower declaration refuses
+     * contravariantly. `BaseSchema`'s own `onClick` / `onChange` / `onSubmit`
+     * already use this spelling for exactly this situation.
+     */
+    onRowClick?: (record: any, event?: any) => void;
     onEdit?: (record: any) => void;
     onDelete?: (record: any) => void;
     /** Enable marker clustering for dense data */

package/dist/ObjectMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectMap.d.ts","sourceRoot":"","sources":["../src/ObjectMap.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAmB,UAAU,EAAY,MAAM,kBAAkB,CAAC;AAY/F,OAAO,kCAAkC,CAAC;AAkB1C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACjC,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkcD,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CA2jB9C,CAAC;AAEF,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ObjectMap.d.ts","sourceRoot":"","sources":["../src/ObjectMap.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAmB,UAAU,EAAY,MAAM,kBAAkB,CAAC;AA0B/F,OAAO,kCAAkC,CAAC;AAoD1C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAChD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACjC,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAqfD,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAm9B9C,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,44 @@
 import { default as React } from 'react';
-import { ObjectMap, ObjectMapProps } from './ObjectMap';
+import { ObjectMap, ObjectMapProps } from './ObjectMap.js';
 export { ObjectMap };
 export type { ObjectMapProps };
 export declare const ObjectMapRenderer: React.FC<any>;
+/**
+ * ⛔ The bare `map` node type key is RETIRED (objectui#10393, executing the
+ * objectui#8008 family ruling of 2026-09-09, route 3). `object-map` is the one
+ * spelling this plugin serves.
+ *
+ * ## What was here, and why it went
+ *
+ * `ComponentRegistry.register('map', ObjectMapRenderer, { namespace: 'view',
+ * ... })` — a second key on the SAME renderer, which stored both `view:map`
+ * and the bare `map` fallback. The declared face admitted only one of the two:
+ * `ObjectMapSchema.type` is the literal `'object-map'` and `AnyComponentSchema`
+ * has no `map` arm, so a node authored `type: 'map'` failed validation
+ * (`invalid_union`) while the registry mounted it. Two published faces,
+ * opposite verdicts — the shape objectui#8008 retired for `gantt`.
+ *
+ * ## Why unregistering is the whole retirement here — measured, not assumed
+ *
+ * ⚠️ `BaseSchemaCore` ends `.passthrough()` (and `BaseSchema` closed with
+ * `[key: string]: any` until objectui#8347), so a dropped MEMBER KEY is KEPT,
+ * not refused, on the zod face (the objectui#7664 failure). That hazard needs a schema face to arise on, and this
+ * TYPE NAME never had one: in `@object-ui/types` the literal `'map'` appears
+ * only in the stored view-type unions (`NamedListView.type`,
+ * `defaultViewType`), never as a component node type, against a firing control
+ * of two for `object-map` (`objectql.ts` + its Zod mirror). There is no arm to
+ * convert into a named refusal, so unregistering IS the retirement.
+ *
+ * ## ⛔ Two layers, and only one of them moved
+ *
+ * The string `map` also names a STORED `NamedListView.type` — the value
+ * `CreateViewDialog` writes and every tenant's database holds. That layer is
+ * untouched: `plugin-view`'s `ObjectView` and `plugin-list`'s `ListView` each
+ * map a stored `map` view onto the node type they emit (their `case 'map'`
+ * branches), and both already emit `object-map`. ⇒ Every map view any user
+ * ever created through the console already renders through the surviving
+ * spelling; this retirement moves zero stored documents.
+ *
+ * Pinned in `src/index.bareMapKeyRetired-10393.test.tsx`.
+ */
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAO1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,CAAC;AAwB/B,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAgB3C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAQ1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,CAAC;AAwB/B,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAoB1C,CAAC;AAmEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}