@nika-js/onlymap 0.5.3 → 0.5.6

package/onlymapjs.html-data.json

@@ -339,7 +339,7 @@
         },
         {
           "name": "data",
-          "description": "Data URL (JSON, GeoJSON, CSV/TSV, Arrow/GeoArrow IPC, Shapefile .shp, KML) or wss:// stream; omit for inline <script type=\"application/json\">."
+          "description": "Data URL (JSON, GeoJSON, CSV/TSV, Arrow/GeoArrow IPC, Shapefile .shp, KML, GPX, FlatGeobuf .fgb, GeoParquet .parquet, CityJSON) or wss:// stream; omit for inline <script type=\"application/json\">."
         },
         {
           "name": "label",
@@ -430,19 +430,19 @@
         },
         {
           "name": "get-position",
-          "description": "Accessor for deck.gl getPosition — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPosition — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-fill-color",
-          "description": "Accessor for deck.gl getFillColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getFillColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-line-color",
-          "description": "Accessor for deck.gl getLineColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getLineColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-radius",
-          "description": "Accessor for deck.gl getRadius — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getRadius — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "radius",
@@ -526,7 +526,7 @@
         },
         {
           "name": "highlight-color",
-          "description": "Accessor for deck.gl highlightColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl highlightColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "radius-scale",
@@ -558,15 +558,15 @@
         },
         {
           "name": "get-line-width",
-          "description": "Accessor for deck.gl getLineWidth — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getLineWidth — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-pixel-offset",
-          "description": "Accessor for deck.gl getPixelOffset — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPixelOffset — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-point-radius",
-          "description": "Accessor for deck.gl getPointRadius — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPointRadius — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "point-radius-units",
@@ -578,7 +578,7 @@
         },
         {
           "name": "get-elevation",
-          "description": "Accessor for deck.gl getElevation — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getElevation — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "extruded",
@@ -638,23 +638,23 @@
         },
         {
           "name": "get-icon",
-          "description": "Accessor for deck.gl getIcon — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getIcon — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-icon-angle",
-          "description": "Accessor for deck.gl getIconAngle — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getIconAngle — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-icon-color",
-          "description": "Accessor for deck.gl getIconColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getIconColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-icon-pixel-offset",
-          "description": "Accessor for deck.gl getIconPixelOffset — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getIconPixelOffset — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-icon-size",
-          "description": "Accessor for deck.gl getIconSize — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getIconSize — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "text-size-max-pixels",
@@ -722,43 +722,43 @@
         },
         {
           "name": "get-text",
-          "description": "Accessor for deck.gl getText — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getText — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-angle",
-          "description": "Accessor for deck.gl getTextAngle — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextAngle — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-color",
-          "description": "Accessor for deck.gl getTextColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-pixel-offset",
-          "description": "Accessor for deck.gl getTextPixelOffset — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextPixelOffset — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-size",
-          "description": "Accessor for deck.gl getTextSize — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextSize — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-anchor",
-          "description": "Accessor for deck.gl getTextAnchor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextAnchor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-alignment-baseline",
-          "description": "Accessor for deck.gl getTextAlignmentBaseline — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextAlignmentBaseline — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-background-color",
-          "description": "Accessor for deck.gl getTextBackgroundColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextBackgroundColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-border-color",
-          "description": "Accessor for deck.gl getTextBorderColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextBorderColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-text-border-width",
-          "description": "Accessor for deck.gl getTextBorderWidth — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTextBorderWidth — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "line-joint-rounded",
@@ -790,7 +790,7 @@
         },
         {
           "name": "get-polygon",
-          "description": "Accessor for deck.gl getPolygon — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPolygon — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "full3d",
@@ -798,15 +798,15 @@
         },
         {
           "name": "get-subtext",
-          "description": "Accessor for deck.gl getSubtext — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getSubtext — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-color",
-          "description": "Accessor for deck.gl getColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-size",
-          "description": "Accessor for deck.gl getSize — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getSize — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "layout",
@@ -826,15 +826,15 @@
         },
         {
           "name": "get-orientation",
-          "description": "Accessor for deck.gl getOrientation — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getOrientation — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-scale",
-          "description": "Accessor for deck.gl getScale — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getScale — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-translation",
-          "description": "Accessor for deck.gl getTranslation — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTranslation — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "size-scale",
@@ -854,7 +854,7 @@
         },
         {
           "name": "get-transform-matrix",
-          "description": "Accessor for deck.gl getTransformMatrix — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTransformMatrix — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "tileset",
@@ -878,7 +878,7 @@
         },
         {
           "name": "get-point-color",
-          "description": "Accessor for deck.gl getPointColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPointColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "loader",
@@ -906,31 +906,31 @@
         },
         {
           "name": "get-source-position",
-          "description": "Accessor for deck.gl getSourcePosition — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getSourcePosition — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-target-position",
-          "description": "Accessor for deck.gl getTargetPosition — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTargetPosition — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-source-color",
-          "description": "Accessor for deck.gl getSourceColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getSourceColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-target-color",
-          "description": "Accessor for deck.gl getTargetColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTargetColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-width",
-          "description": "Accessor for deck.gl getWidth — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getWidth — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-height",
-          "description": "Accessor for deck.gl getHeight — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getHeight — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-tilt",
-          "description": "Accessor for deck.gl getTilt — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTilt — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "great-circle",
@@ -1026,7 +1026,7 @@
         },
         {
           "name": "get-angle",
-          "description": "Accessor for deck.gl getAngle — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getAngle — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "joint-rounded",
@@ -1046,11 +1046,11 @@
         },
         {
           "name": "get-path",
-          "description": "Accessor for deck.gl getPath — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPath — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-normal",
-          "description": "Accessor for deck.gl getNormal — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getNormal — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "_normalize",
@@ -1066,15 +1066,15 @@
         },
         {
           "name": "get-background-color",
-          "description": "Accessor for deck.gl getBackgroundColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getBackgroundColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-border-color",
-          "description": "Accessor for deck.gl getBorderColor — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getBorderColor — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-border-width",
-          "description": "Accessor for deck.gl getBorderWidth — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getBorderWidth — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "background-border-radius",
@@ -1134,23 +1134,23 @@
         },
         {
           "name": "get-alignment-baseline",
-          "description": "Accessor for deck.gl getAlignmentBaseline — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getAlignmentBaseline — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-content-box",
-          "description": "Accessor for deck.gl getContentBox — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getContentBox — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-pentagon",
-          "description": "Accessor for deck.gl getPentagon — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getPentagon — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-geohash",
-          "description": "Accessor for deck.gl getGeohash — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getGeohash — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-hexagons",
-          "description": "Accessor for deck.gl getHexagons — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getHexagons — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "high-precision",
@@ -1162,7 +1162,7 @@
         },
         {
           "name": "get-hexagon",
-          "description": "Accessor for deck.gl getHexagon — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getHexagon — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "extent",
@@ -1226,11 +1226,11 @@
         },
         {
           "name": "get-quadkey",
-          "description": "Accessor for deck.gl getQuadkey — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getQuadkey — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-s2-token",
-          "description": "Accessor for deck.gl getS2Token — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getS2Token — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "elevation-data",
@@ -1266,7 +1266,7 @@
         },
         {
           "name": "get-timestamps",
-          "description": "Accessor for deck.gl getTimestamps — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getTimestamps — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "grid-origin",
@@ -1274,7 +1274,7 @@
         },
         {
           "name": "get-weight",
-          "description": "Accessor for deck.gl getWeight — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getWeight — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "gpu-aggregation",
@@ -1302,11 +1302,11 @@
         },
         {
           "name": "get-color-value",
-          "description": "Accessor for deck.gl getColorValue — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getColorValue — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-color-weight",
-          "description": "Accessor for deck.gl getColorWeight — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getColorWeight — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "color-aggregation",
@@ -1334,11 +1334,11 @@
         },
         {
           "name": "get-elevation-value",
-          "description": "Accessor for deck.gl getElevationValue — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getElevationValue — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "get-elevation-weight",
-          "description": "Accessor for deck.gl getElevationWeight — expression language: $field, scale(), arithmetic."
+          "description": "Accessor for deck.gl getElevationWeight — expression language: $field, scale(), formatDate(), arithmetic."
         },
         {
           "name": "elevation-aggregation",
@@ -1769,6 +1769,40 @@
           "name": "field",
           "description": "Data field (filter / vega-lite widgets)."
         },
+        {
+          "name": "format",
+          "description": "Filter value-label format. Use date for epoch-millisecond fields; default number.",
+          "values": [
+            {
+              "name": "number"
+            },
+            {
+              "name": "date"
+            }
+          ]
+        },
+        {
+          "name": "date-style",
+          "description": "Filter date label style when format=\"date\".",
+          "values": [
+            {
+              "name": "date"
+            },
+            {
+              "name": "datetime"
+            },
+            {
+              "name": "time"
+            },
+            {
+              "name": "iso"
+            }
+          ]
+        },
+        {
+          "name": "time-zone",
+          "description": "Filter date label time zone when format=\"date\": UTC (default), local, or an IANA zone such as Asia/Singapore."
+        },
         {
           "name": "story",
           "description": "Story id (player widget)."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -150,8 +150,11 @@
     "d3-color": "^3.1.0",
     "d3-interpolate": "^3.0.1",
     "d3-scale": "^4.0.2",
+    "flatgeobuf": "^4.4.0",
     "fzstd": "^0.1.1",
     "happy-dom": "^20.10.6",
+    "hyparquet": "^1.27.1",
+    "hyparquet-compressors": "^1.1.1",
     "jotai": "^2.20.2",
     "maplibre-gl": "^5.24.0",
     "mobx": "^6.16.1",

package/skills/onlymapjs/SKILL.md

@@ -23,7 +23,7 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.5.3` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.3/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
+For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.5.6` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.6/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
 
 ## React Projects
 
@@ -52,6 +52,8 @@ Load the smallest reference needed for the task:
 - Attribute names are kebab-case: `get-fill-color`, `radius-units`, `line-width-min-pixels`.
 - Accessor values are expressions: `get-position="[$lon, $lat]"`.
 - `scale()` always needs an explicit `domain=`.
+- Format epoch-millisecond or ISO fields with the safe `formatDate()` built-in, e.g. `get-text="formatDate($time, 'datetime', 'UTC')"`. Do not use `new Date()`, `Intl`, or method calls in restricted expressions.
+- For a built-in filter over epoch milliseconds, add `format="date"` with optional `date-style="date|datetime|time|iso"` and `time-zone="UTC|local|<IANA zone>"`; do not hand-roll a time slider only to format its labels.
 - ScatterplotLayer points need an explicit size — `radius="6" radius-units="pixels"`, `get-radius="..."`, or `radius-min-pixels="..."`: deck's default is 1 METER, sub-pixel at city zooms, and validation warns on layers with no radius source.
 - Prefer canonical color expressions — a `sequential`/`diverging`/`threshold` `scale()` or an equality ternary chain — over hand-rolled arithmetic: the legend widget parses these shapes and renders a matching gradient ramp / class ranges / category palette automatically.
 - Inline handlers such as `onclick` are wrong. Use `data-emit`, `<om-behavior>`, or widget scripts.

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.3/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.3"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.6/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.6"></script>
 ```
 
 Always include `onlymapjs.css` — it carries the MapLibre basemap styles and the no-JS fallback rules (`<om-fallback>` / default banner). For the fallback to work in script-disabled previews it must load without JavaScript: a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages (a bundler-emitted stylesheet is fine in npm projects).
@@ -81,10 +81,21 @@ get-position="[$lon, $lat]"
 get-radius="$population * 0.001"
 get-fill-color="$value > 100 ? [255,0,0] : [0,128,255]"
 get-fill-color="scale($depth, sequential, ['#ffffcc','#800026'], domain=[0,700])"
+get-text="formatDate($time, 'datetime', 'UTC')"
 ```
 
 `$field` works on flat rows, GeoJSON properties, columnar JSON, CSV/TSV columns, and Arrow point columns.
 
+Date formatting is a safe built-in rather than an opt-in to arbitrary JavaScript:
+
+```html
+get-text="formatDate($time)"
+get-text="formatDate($time, 'date')"
+get-text="formatDate($time, 'datetime', 'Asia/Singapore')"
+```
+
+`formatDate(value, style?, timeZone?)` accepts epoch-millisecond numbers/numeric strings or ISO date strings. Numeric values are always milliseconds—multiply Unix seconds by 1000 before formatting. Styles are `date`, `datetime` (default), `time`, and `iso`; the default time zone is `UTC`, while `local` opts into the viewer's zone and IANA names select a specific zone. Invalid values produce an empty string. Restricted expressions still reject `new Date()`, `Intl`, and instance-method calls.
+
 Smart shorthands:
 
 - `color="#1f9e89"` sets a constant `getFillColor` when no explicit `get-fill-color` exists, and always feeds the legend swatch.
@@ -102,6 +113,17 @@ Filtering:
 filter-field="magnitude" filter-range="[4, 10]"
 ```
 
+For an epoch-millisecond filter, format the built-in widget's numeric labels declaratively:
+
+```html
+<om-layer id="quakes" type="GeoJsonLayer" data="./quakes.geojson"
+          filter-field="time" filter-range="[1782889284760, 1785480717910]"></om-layer>
+<om-widget type="filter" layer="quakes" field="time"
+           format="date" date-style="datetime" time-zone="UTC"></om-widget>
+```
+
+`format` is `number` (default) or `date`. With `format="date"`, `date-style` uses the same four styles as `formatDate()` and `time-zone` defaults to `UTC`.
+
 
 
 ### Built-In Layer Types
@@ -151,6 +173,9 @@ External layer classes become manifest types via `OmMap.registerLayer({type, dec
 | Arrow / GeoArrow IPC | `data="./big.arrow"`                                        | Points stay columnar; lines/polygons become GeoJSON features. |
 | Shapefile            | `data="./countries.shp"`                                    | Loads sidecars and joins `.dbf` attributes.                   |
 | KML                  | `data="./tour.kml"`                                         | Placemarks become GeoJSON features.                           |
+| GPX                  | `data="./hike.gpx"` (opt. `#waypoints`/`#tracks`/`#routes`) | Waypoints/tracks/routes → GeoJSON features, each tagged `_gpxKind`; a URL fragment selects one part (no fragment = all). |
+| FlatGeobuf           | `data="./cities.fgb"`                                       | Cloud-native binary vector — whole-file decode to GeoJSON features (bbox-streaming is a later phase). |
+| GeoParquet           | `data="./data.parquet"` (or `.geoparquet`)                 | Cloud-native columnar vector — all-Point files stay columnar, lines/polygons become GeoJSON features; needs the `geo` metadata (WKB geometry) and CRS84/EPSG:4326 (a projected CRS errors — reproject first). |
 | CityJSON             | `data="./tile.city.json"`                                   | 3D city models → extruded footprints, or `?om-surfaces=1` for real per-face roof geometry; see below. |
 | CityJSONSeq          | `data="./tile.city.jsonl"`                                  | Same, streamed line by line as it downloads.                  |
 | WebSocket            | `data="wss://feed" key="id" flush="250ms" source="decoder"` | Upsert-by-key stream.                                         |
@@ -296,11 +321,30 @@ Examples:
 ```html
 <om-widget type="legend" position="bottom-right" title="Layers" interactive></om-widget>
 <om-widget type="filter" layer="quakes" field="magnitude" position="top-left"></om-widget>
+<om-widget type="filter" layer="quakes" field="time" format="date"
+           date-style="datetime" time-zone="UTC" position="bottom-center"></om-widget>
 <om-widget type="draw" target="sketch" modes="point line polygon" save="both"></om-widget>
 <om-widget type="basemap-switcher" options="positron dark-matter liberty osm" position="top-right"></om-widget>
 ```
 
-Custom widget:
+### Custom widgets & event emission
+
+**Reach for a built-in first.** A plain value/time slider is a built-in:
+`<om-widget type="filter" layer="quakes" field="time" format="date">` — it
+renders readable date labels AND wires the `filter-layer` action for you (pair
+it with the layer's `filter-field`). Author a custom widget ONLY for bespoke UI
+or logic the built-ins don't cover — most "it looked right but didn't work"
+widgets should have been a `type="filter"`/`legend`/`vega-lite` built-in.
+
+A custom widget is an `<om-widget>` with **no `type`** plus inline HTML and a
+`<script type="om/widget">` block. The script is full JS, evaluated ONCE at
+connect with `this` bound to the `<om-widget>` element: set `this.watch` (a
+list of re-render triggers) and `this.render = (ctx) => {…}`. `vegaEmbed`/`d3`
+are available. Content renders in shadow DOM — reach it with `this.$(selector)`
+and `this.root`.
+
+**Read map state** through `ctx` (the `render` argument), re-rendering when a
+watched token fires:
 
 ```html
 <om-widget position="top-left">
@@ -315,20 +359,60 @@ Custom widget:
 </om-widget>
 ```
 
-Widget context:
-
-- `ctx.layers`
-- `ctx.data(id)`
-- `ctx.dataInViewport(id)`
-- `ctx.stats(id, field, { scope: "viewport" })`
-- `ctx.selection`
-- `ctx.viewport`
-- `ctx.history` — `{ canUndo, canRedo }`; re-render on changes via the `history` watch token
-- `ctx.emit(action, payload)`
-
-Watch tokens: `data:<layerId>`, `viewport`, `selection`, `layers` (fires on layer add/remove, visibility, and filter changes), `basemap`, `lighting`, `terrain`, `history`, `widgets` (fires on a `widgets-hidden` hide-all toggle).
-
-Use `this.$()` and `this.root`; widgets render in shadow DOM.
+- `ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`,
+  `ctx.stats(id, field, { scope: "viewport" })`, `ctx.selection`,
+  `ctx.viewport`, `ctx.history` (`{ canUndo, canRedo }`).
+- Watch tokens: `data:<layerId>`, `viewport`, `selection`, `layers` (add/remove,
+  visibility, filter changes), `basemap`, `lighting`, `terrain`, `history`,
+  `widgets` (`widgets-hidden` hide-all toggle).
+
+**Drive the map — the emission contract.** This is the part authors get wrong.
+A widget NEVER mutates the map directly and NEVER dispatches its own
+`CustomEvent` hoping the map listens. It **emits a registered action**, exactly
+two ways:
+
+1. **Declarative `data-emit`** (no script): `data-emit="<action>"` + `data-*`
+   payload keys on an element. Fires on **click** (non-form elements) or
+   **change** (form controls — `input`/`select`/`textarea`, whose `.value` is
+   auto-merged into the payload). `data-*` keys camelCase (`data-feature-id` →
+   `featureId`) and arrive as **strings** — fine for `toggle-layer`/`fly-to`,
+   but a numeric/array payload (a slider's `range: [min, max]`) needs `ctx.emit`.
+   ```html
+   <button data-emit="toggle-layer" data-layer="quakes">Toggle quakes</button>
+   ```
+
+2. **Programmatic `ctx.emit(action, payload)`** — for typed payloads. Wire it
+   INSIDE `render` so `ctx` is in scope, assigning `.oninput`/`.onclick`
+   (idempotent across re-renders; prefer over `addEventListener`, which stacks a
+   fresh listener every render):
+   ```html
+   <om-widget position="bottom-center">
+     <input id="day" type="range" min="1" max="14" step="1" value="1">
+     <script type="om/widget">
+       this.render = (ctx) => {
+         this.$("#day").oninput = (e) => {
+           const d = Number(e.target.value);
+           ctx.emit("filter-layer", { layer: "quakes", field: "day", range: [d, d] });
+         };
+       };
+     </script>
+   </om-widget>
+   ```
+
+**NEVER inline handlers** (`onclick="…"`, `oninput="ctx.emit(…)"`): `ctx` is not
+a global, they execute in page scope, and CSP blocks them — the widget looks
+right and silently emits nothing. This is the #1 custom-widget failure, and
+validation errors on it.
+
+**Actions a widget can emit** (payload keys): `filter-layer`
+`{layer, field?, range:[min,max]}` (value/time sliders), `toggle-layer`
+`{layer, visible?}`, `fly-to` `{center:[lng,lat], zoom?, pitch?, bearing?,
+duration?}`, `zoom-to-feature` `{layer, featureId, duration?}`, `set-basemap`
+`{basemap}`, `set-lighting`/`set-terrain`, `highlight-feature`
+`{layer, featureId}`, `show-overlay`/`hide-overlay` `{target}`,
+`story-play`/`story-pause`/`story-seek` `{story, t?}`, `undo`/`redo`,
+`zoom-in`/`zoom-out`, `set-widgets-visible` `{visible}`. Register your own with
+`OmMap.registerAction(name, (payload, mapEl) => …)`.
 
 ### `<om-overlay>`
 
@@ -494,4 +578,3 @@ For 3D Tiles LOD/refinement experiments, use:
             maximum-memory-usage="256"
             view-distance-scale="0.85"></om-layer>
 ```
-