@studiometa/ui-mapbox 0.0.1 → 1.10.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/AbstractMapboxControl.d.ts +53 -0
  2. package/AbstractMapboxControl.js +70 -0
  3. package/AbstractMapboxControl.js.map +1 -0
  4. package/AbstractMapboxMapChild.d.ts +229 -0
  5. package/AbstractMapboxMapChild.js +336 -0
  6. package/AbstractMapboxMapChild.js.map +1 -0
  7. package/LICENSE.md +110 -0
  8. package/MapboxCluster.d.ts +208 -0
  9. package/MapboxCluster.js +418 -0
  10. package/MapboxCluster.js.map +1 -0
  11. package/MapboxClusterItem.d.ts +130 -0
  12. package/MapboxClusterItem.js +182 -0
  13. package/MapboxClusterItem.js.map +1 -0
  14. package/MapboxFullscreenControl.d.ts +21 -0
  15. package/MapboxFullscreenControl.js +21 -0
  16. package/MapboxFullscreenControl.js.map +1 -0
  17. package/MapboxGeocoder.d.ts +64 -0
  18. package/MapboxGeocoder.js +80 -0
  19. package/MapboxGeocoder.js.map +1 -0
  20. package/MapboxGeolocateControl.d.ts +23 -0
  21. package/MapboxGeolocateControl.js +31 -0
  22. package/MapboxGeolocateControl.js.map +1 -0
  23. package/MapboxImage.d.ts +49 -0
  24. package/MapboxImage.js +83 -0
  25. package/MapboxImage.js.map +1 -0
  26. package/MapboxImages.d.ts +66 -0
  27. package/MapboxImages.js +95 -0
  28. package/MapboxImages.js.map +1 -0
  29. package/MapboxLayer.d.ts +99 -0
  30. package/MapboxLayer.js +148 -0
  31. package/MapboxLayer.js.map +1 -0
  32. package/MapboxMap.d.ts +64 -0
  33. package/MapboxMap.js +131 -0
  34. package/MapboxMap.js.map +1 -0
  35. package/MapboxMarker.d.ts +56 -0
  36. package/MapboxMarker.js +73 -0
  37. package/MapboxMarker.js.map +1 -0
  38. package/MapboxNavigationControl.d.ts +27 -0
  39. package/MapboxNavigationControl.js +28 -0
  40. package/MapboxNavigationControl.js.map +1 -0
  41. package/MapboxPopup.d.ts +51 -0
  42. package/MapboxPopup.js +76 -0
  43. package/MapboxPopup.js.map +1 -0
  44. package/MapboxSource.d.ts +68 -0
  45. package/MapboxSource.js +104 -0
  46. package/MapboxSource.js.map +1 -0
  47. package/README.md +85 -0
  48. package/StoreLocator.d.ts +323 -0
  49. package/StoreLocator.js +538 -0
  50. package/StoreLocator.js.map +1 -0
  51. package/catalog.d.ts +7 -0
  52. package/catalog.js +68 -0
  53. package/catalog.js.map +1 -0
  54. package/dependencies.d.ts +85 -0
  55. package/dependencies.js +84 -0
  56. package/dependencies.js.map +1 -0
  57. package/index.d.ts +18 -0
  58. package/index.js +19 -0
  59. package/index.js.map +1 -0
  60. package/manifest.d.ts +6 -0
  61. package/manifest.js +133 -0
  62. package/manifest.js.map +1 -0
  63. package/package.json +43 -3
  64. package/utils.d.ts +112 -0
  65. package/utils.js +143 -0
  66. package/utils.js.map +1 -0
  67. package/Claude-of-Duty/node_modules/@esbuild/darwin-arm64/bin/esbuild +0 -0
  68. package/alfred-projects-cache.tsv +0 -137
  69. package/claude-501/-Users-titouanmathis--dotfiles/298a49f7-c4b3-4a50-9707-a9c0d0733e95/scratchpad/pptest/config.json +0 -1
  70. package/claude-501/-Users-titouanmathis--dotfiles/298a49f7-c4b3-4a50-9707-a9c0d0733e95/scratchpad/pptest/stub/herdr +0 -8
  71. package/claude-501/-Users-titouanmathis--dotfiles/7d127a50-a71a-411a-bc1f-15b070f909f9/tasks/bg1cckto6.output +0 -4
  72. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/after.toml +0 -298
  73. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/before.toml +0 -298
  74. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/extracted.txt +0 -36
  75. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/final.log +0 -496
  76. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/guard.sh +0 -18
  77. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/lock.check +0 -917
  78. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/mise-registry.json +0 -3827
  79. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/mise.lock.before +0 -917
  80. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/misetest/.config/mise/conf.d/extra.toml +0 -2
  81. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/misetest/.config/mise/mise.lock +0 -47
  82. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/misetest/mise.lock +0 -47
  83. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/misetest/mise.toml +0 -2
  84. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/.github/workflows/mise-check.yml +0 -188
  85. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/.github/workflows/renovate.yml +0 -62
  86. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/mise.lock +0 -917
  87. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/mise.toml +0 -291
  88. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/probe.log +0 -4974
  89. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/probe2.log +0 -22
  90. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/probe3.log +0 -4916
  91. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/probe/renovate.json +0 -62
  92. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/renovate-local.log +0 -670
  93. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/symtest/link/mise.lock +0 -47
  94. package/claude-501/-Users-titouanmathis--dotfiles/dd4cd328-df52-4522-a502-48fa24b7b142/scratchpad/symtest/real/source.toml +0 -4
  95. package/claude-501/-Users-titouanmathis-Lab--studiometa-automations/d6c27f69-577a-468b-9bb3-a45c03a66143/scratchpad/cookie.txt +0 -1
  96. package/gitlab-docs-read.md +0 -8
  97. package/gitlab-instance-limits.txt +0 -8
  98. package/piab-501/piab-devops-019fcbcc991d-59c77b27-fresh-47da8bd318.config +0 -1
  99. package/pins-new.txt +0 -36
  100. package/pins-old.txt +0 -36
  101. package/reply +0 -0
  102. package/zsh0IBbcP +0 -0
  103. package/zsh2LqT39 +0 -0
  104. package/zsh6KJGTP +0 -0
  105. package/zshN1hNdy +0 -0
  106. package/zshNjWSYH +0 -11
  107. package/zshNvB745 +0 -0
  108. package/zshOXC0uH +0 -0
  109. package/zshPG9CFU +0 -0
  110. package/zshVOeZsK +0 -0
  111. package/zshVqIgQS +0 -0
  112. package/zshXTrFg8 +0 -0
  113. package/zshaUGubs +0 -11
  114. package/zshbzOT6d +0 -1
  115. package/zshnbtbGK +0 -0
  116. package/zshpQi1EI +0 -2
  117. package/zshwhMjOD +0 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AbstractMapboxMapChild.js","names":[],"sources":["../AbstractMapboxMapChild.ts"],"sourcesContent":["import { Base, type BaseConfig, type BaseProps } from '@studiometa/js-toolkit';\nimport type { Map } from 'mapbox-gl';\nimport type { MapboxMap } from './MapboxMap.js';\n\nexport interface AbstractMapboxMapChildProps extends BaseProps {}\n\n/**\n * Document-level event a `MapboxMap` dispatches when its instance mounts, so a\n * child that mounted *before* its map (e.g. an eagerly registered child under a\n * lazily imported map) can retry resolving its parent and inject itself once the\n * map is connected. The dispatching `MapboxMap` instance travels in `detail`.\n */\nexport const MAPBOX_MAP_CONNECTED = 'mapbox-map:connected';\n\n/**\n * Base class for every component living inside a `MapboxMap`.\n *\n * Children are self-sufficient and dynamic-DOM-native: they resolve their\n * parent `MapboxMap` on their own via `$closest`, wait for the map to be ready\n * with `whenMapReady`, then inject their contribution. Each component is\n * registered independently (e.g. with `registerComponent`, optionally behind a\n * lazy `importWhen*` helper); registration order does not matter because a child\n * resolves its map through the connected-event retry. Once registered,\n * js-toolkit's document-wide `MutationObserver` mounts them whenever their\n * element enters the DOM —\n * statically, `Fetch`-injected or `appendChild`-ed — and terminates them when it\n * leaves, at which point they remove their contribution again.\n *\n * The base hardens three things every child inherits, rather than relying on\n * per-subclass discipline:\n *\n * 1. **Guarded injection & teardown** — mapbox-gl throws readily (a duplicate\n * source id, any style-touching call after `map.remove()`), and js-toolkit's\n * global queue runs lifecycle hooks with no try/catch: a single synchronous\n * throw wedges the queue and freezes every mount/destroy on the page. The\n * ready callback and the subclass teardown (`__onDestroyed`) are both run\n * inside a try/catch that routes to `$warn` + a `map-error` event and never\n * rethrows.\n * 2. **Dead-map safety** — once ready, the child subscribes to the map's own\n * `remove` event; when it fires the cached map reference is dropped so no\n * teardown ever calls a method on a removed map (which throws `TypeError`).\n * 3. **Retryable, standing resolution** — resolution is not one-shot: a child\n * with no map yet waits for `MAPBOX_MAP_CONNECTED`, and a map destroy →\n * remount re-injects the child on the new map's next load.\n * 4. **Style-reload re-injection** — a `map.setStyle()` wipes the whole style\n * (every source/layer/sprite) while the map instance and the still-mounted\n * children survive, so the declarative resources would silently vanish. Once\n * ready, the child subscribes to the map's `style.load` — fired once per\n * style load, the Mapbox-recommended hook for re-adding custom sources/layers\n * when switching base style — and re-runs its injection so it re-adds its\n * contribution onto the fresh style (H7, PR #567 review). The re-run reuses\n * the same containment as the first injection and is guarded on the resource\n * already being present, so it never double-injects.\n *\n * @see https://ui.studiometa.dev/reference/items/MapboxMap/\n */\nexport class AbstractMapboxMapChild<T extends BaseProps = BaseProps> extends Base<\n T & AbstractMapboxMapChildProps\n> {\n /**\n * Config.\n */\n static config: BaseConfig = {\n name: 'AbstractMapboxMapChild',\n emits: ['map-error'],\n };\n\n /**\n * The parent `MapboxMap` resolved at ready-time.\n *\n * `destroyed()` runs *after* the element has been detached from the DOM (e.g.\n * a `Fetch` list swap, or the parent map itself being removed), and a\n * `$closest` lookup on a disconnected node returns nothing — a real bug that\n * would leave the child's contribution stuck on the map. Caching the resolved\n * references at ready-time keeps every teardown path working through the\n * detach.\n * @private\n */\n __readyMapboxMap?: MapboxMap;\n\n /**\n * The Mapbox `Map` instance resolved at ready-time, cached for teardown. It is\n * dropped as soon as the map's `remove` event fires so teardown never touches\n * a removed map.\n * @private\n */\n __readyMap?: Map;\n\n /**\n * The injection callback registered through `whenMapReady`, kept so it can be\n * re-run against a new map when the current one is destroyed and remounted.\n *\n * The callback may be synchronous or `async`: a returned promise is awaited\n * inside the same containment as a synchronous body, so a rejection routes to\n * `$warn` + the `map-error` event instead of surfacing as an unhandled rejection.\n * @private\n */\n __readyCallback?: (map: Map) => void | Promise<void>;\n\n /**\n * Off handler for a still-pending `map-load` subscription, flushed on destroy\n * so a child removed before the map finished loading leaves no listener behind.\n * @private\n */\n __offMapReady?: () => void;\n\n /**\n * Off handler for the ready map's `remove` subscription.\n * @private\n */\n __offMapRemove?: () => void;\n\n /**\n * Off handler for the ready map's `style.load` re-injection subscription.\n * @private\n */\n __offStyleReload?: () => void;\n\n /**\n * Off handler for the document-level `MAPBOX_MAP_CONNECTED` retry subscription.\n * @private\n */\n __offConnected?: () => void;\n\n /**\n * The closest parent `MapboxMap` component instance.\n */\n get mapboxMap() {\n const mapboxMap = this.$closest<MapboxMap>('MapboxMap');\n\n if (!mapboxMap) {\n this.$warn(\n 'Can not find the parent map, does this component has a parent MapboxMap component?',\n );\n }\n\n return mapboxMap;\n }\n\n /**\n * The Mapbox `Map` instance of the closest parent `MapboxMap` component.\n */\n get map() {\n return this.mapboxMap?.map;\n }\n\n /**\n * Run a callback once the parent map is ready — now, on the next `map-load`,\n * or once a `MapboxMap` connects if none exists yet.\n *\n * The callback is stored so it can be re-run on a fresh map after a destroy →\n * remount. It is wrapped so a throw never propagates into the global queue, is\n * never fired after the child has been destroyed, and the resolved\n * map/`MapboxMap` are cached before it runs so teardown can reach them even\n * once the element is detached.\n *\n * The callback may be `async`: a subclass that awaits (image loading, cluster\n * expansion, ...) must additionally guard against the map changing under it by\n * checking `this.__readyMap === map` after every `await`, since the map it was\n * handed can be removed — or replaced by another — while the promise is in\n * flight. A rejected promise is contained here, never rethrown.\n *\n * @param {(map: Map) => void | Promise<void>} cb The work to run against the ready map.\n */\n whenMapReady(cb: (map: Map) => void | Promise<void>): void {\n this.__readyCallback = cb;\n this.__resolveMap();\n }\n\n /**\n * Resolve the parent `MapboxMap` and bind to it, or wait for one to connect.\n * @private\n */\n __resolveMap(): void {\n const mapboxMap = this.$closest<MapboxMap>('MapboxMap');\n\n if (!mapboxMap) {\n this.__waitForConnectedMap();\n return;\n }\n\n this.__bindToMap(mapboxMap);\n }\n\n /**\n * Subscribe once to `MAPBOX_MAP_CONNECTED` and retry resolution when a map\n * whose element is an ancestor of this child connects.\n * @private\n */\n __waitForConnectedMap(): void {\n if (this.__offConnected) {\n return;\n }\n\n const handler = (event: Event) => {\n const mapboxMap = (event as CustomEvent<MapboxMap>).detail;\n\n // Ignore maps that are not an ancestor of this child: several independent\n // maps can live on the same page.\n if (!mapboxMap?.$el?.contains(this.$el)) {\n return;\n }\n\n this.__offConnected?.();\n this.__offConnected = undefined;\n this.__resolveMap();\n };\n\n document.addEventListener(MAPBOX_MAP_CONNECTED, handler);\n this.__offConnected = () => document.removeEventListener(MAPBOX_MAP_CONNECTED, handler);\n }\n\n /**\n * Bind to a resolved `MapboxMap`: run the ready callback now if its map is\n * already loaded, otherwise once on `map-load`.\n * @private\n * @param {MapboxMap} mapboxMap\n */\n __bindToMap(mapboxMap: MapboxMap): void {\n // Resolve the concrete map now and subscribe to its `remove` immediately.\n // Binding the remove handler here rather than after load means a map removed\n // *while its load is still pending* re-resolves the child onto a replacement\n // instead of stranding it: the pending `map-load` subscription is flushed and\n // the child parks on `MAPBOX_MAP_CONNECTED` again.\n const map = mapboxMap.map;\n\n // The parent's `MapboxMap` instance may exist while its concrete map is not\n // built yet: it resolves `mapbox-gl` asynchronously in `mounted()` before\n // creating the map. Keep waiting on `MAPBOX_MAP_CONNECTED`, which the map\n // dispatches once its instance exists, and bind then.\n if (!map) {\n this.__waitForConnectedMap();\n return;\n }\n\n // Drop any stale pending subscription before (re)binding.\n this.__offMapReady?.();\n this.__offMapReady = undefined;\n\n this.__bindMapRemove(map);\n this.__bindStyleReload(map);\n\n const run = () => {\n // The child may have been destroyed while waiting for the map to load: do\n // not inject anything into a map the child no longer belongs to.\n if (!this.$isMounted) {\n return;\n }\n\n this.__readyMapboxMap = mapboxMap;\n this.__readyMap = map;\n this.__runReadyCallback(map);\n };\n\n if (mapboxMap.isLoaded) {\n run();\n } else {\n this.__offMapReady = mapboxMap.$on(\n 'map-load',\n () => {\n this.__offMapReady = undefined;\n run();\n },\n { once: true },\n );\n }\n }\n\n /**\n * Run the ready callback inside a uniform containment for both synchronous\n * throws and rejected promises: a synchronous body is wrapped in `try/catch`,\n * and an `async` body's returned promise is awaited so its rejection routes to\n * `$warn` + the `map-error` event instead of becoming an unhandled rejection.\n * Neither path ever rethrows into the global lifecycle queue.\n * @private\n * @param {Map} map\n */\n __runReadyCallback(map: Map): void {\n let result: void | Promise<void>;\n\n try {\n result = this.__readyCallback?.(map);\n } catch (err) {\n this.__handleError(err);\n return;\n }\n\n if (result && typeof (result as Promise<void>).then === 'function') {\n Promise.resolve(result).catch((err) => this.__handleError(err));\n }\n }\n\n /**\n * Subscribe once to the map's own `remove` event so teardown never runs\n * against a removed map, and so the child re-injects on a remounted map.\n * @private\n * @param {Map} map\n */\n __bindMapRemove(map: Map): void {\n this.__offMapRemove?.();\n this.__offMapRemove = undefined;\n\n // Degrade gracefully for minimal map doubles without an event emitter: a\n // real mapbox map always exposes `on`/`off`.\n if (typeof map?.on !== 'function') {\n return;\n }\n\n const handler = () => {\n this.__offMapRemove?.();\n this.__offMapRemove = undefined;\n\n // Let the subclass flush any map-scoped listener while the map is still\n // referenceable: once `__readyMap` is cleared its teardown can no longer\n // reach the map to `off` them.\n try {\n this.__onMapRemove(map);\n } catch (err) {\n this.__handleError(err);\n }\n\n // A map removed before it finished loading still has a pending `map-load`\n // subscription on the (now dead) `MapboxMap`: flush it so the child does\n // not try to bind on a load that will never come.\n this.__offMapReady?.();\n this.__offMapReady = undefined;\n // The style-reload watch was bound to the now-dead map: drop it too so no\n // `style.load` re-injection ever fires against a removed map.\n this.__offStyleReload?.();\n this.__offStyleReload = undefined;\n this.__readyMap = undefined;\n this.__readyMapboxMap = undefined;\n\n // The map went away, not the child: wait for a new one to connect and\n // re-run the injection against it.\n if (this.$isMounted && this.__readyCallback) {\n this.__waitForConnectedMap();\n }\n };\n\n map.on('remove', handler);\n this.__offMapRemove = () => map.off('remove', handler);\n }\n\n /**\n * Subscribe to the map's `style.load` so the child re-runs its injection after\n * a `setStyle` replaces the whole style, re-adding the source/layer/sprite it\n * would otherwise have silently lost.\n *\n * `style.load` fires once per style load — Mapbox's own recommended hook for\n * re-adding custom sources and layers when switching base style — so it does\n * not need the `styledata` de-duplication a broader `styledata` handler would.\n * The handler bails until the child has actually finished its first injection\n * on this map (`__readyMap === map`): at the *initial* style load `__readyMap`\n * is not set yet (the first injection runs on `map-load`), so this never\n * double-injects on mount and only re-injects on a genuine later `setStyle`.\n * @private\n * @param {Map} map\n */\n __bindStyleReload(map: Map): void {\n this.__offStyleReload?.();\n this.__offStyleReload = undefined;\n\n // Degrade gracefully for minimal map doubles without an event emitter.\n if (typeof map?.on !== 'function') {\n return;\n }\n\n const handler = () => {\n // Only re-inject once the first injection has run against this very map,\n // and only while still mounted with work to do. Re-runs against a map the\n // child no longer owns (removed/replaced) are the `remove` path's job.\n if (!this.$isMounted || !this.__readyCallback || this.__readyMap !== map) {\n return;\n }\n\n // Reuse the first-injection containment. Each subclass callback guards on\n // whether its resource is already present (`getSource`/`getLayer`/\n // `hasImage`), so re-running is safe and re-claims ownership with a fresh\n // liveness probe against the new style.\n this.__runReadyCallback(map);\n };\n\n map.on('style.load', handler);\n this.__offStyleReload = () => map.off('style.load', handler);\n }\n\n /**\n * Contain an error raised by a guarded injection or teardown: warn and emit an\n * `map-error` event, but never rethrow into the global queue.\n * @private\n * @param {unknown} err\n */\n __handleError(err: unknown): void {\n this.$warn(err);\n this.$emit('map-error', err);\n }\n\n /**\n * Hook run when the ready map fires its own `remove` event, while the map is\n * still referenceable (before `__readyMap` is cleared).\n *\n * Subclasses that attach map-scoped listeners (a layer waiting on\n * `sourcedata`, a cluster's per-layer click/hover handlers) override this to\n * `off` them against the map they were bound to — the removed map — since\n * their `__onDestroyed` runs later with `__readyMap` already `undefined` and\n * could not reach the map to unsubscribe.\n * @protected\n * @param {Map} _map The map being removed.\n */\n __onMapRemove(_map: Map) {}\n\n /**\n * Teardown hook implemented by subclasses instead of `destroyed()`.\n *\n * It runs inside the base's guard (see `destroyed`) so a throwing teardown — a\n * style-touching mapbox call, most often — can never wedge the global queue.\n * Implementations read the cached `__readyMap`, which is already `undefined`\n * when the map has been removed, and must not call `super`.\n * @protected\n */\n __onDestroyed() {}\n\n /**\n * Destroyed hook.\n *\n * Runs the guarded subclass teardown, then flushes every base subscription\n * (`map-load`, the map's `remove`, the connected retry). Subclasses override\n * `__onDestroyed` rather than this method.\n */\n destroyed() {\n try {\n this.__onDestroyed();\n } catch (err) {\n this.__handleError(err);\n }\n\n this.__offMapReady?.();\n this.__offMapReady = undefined;\n this.__offMapRemove?.();\n this.__offMapRemove = undefined;\n this.__offStyleReload?.();\n this.__offStyleReload = undefined;\n this.__offConnected?.();\n this.__offConnected = undefined;\n this.__readyCallback = undefined;\n }\n}\n\nexport default AbstractMapboxMapChild;\n"],"mappings":"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"}
package/LICENSE.md ADDED
@@ -0,0 +1,110 @@
1
+ # Functional Source License, Version 1.1, MIT Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-MIT
6
+
7
+ ## Notice
8
+
9
+ Copyright 2025 Studio Meta
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the MIT license that is effective on the second anniversary of the date we make
91
+ the Software available. On or after that date, you may use the Software under
92
+ the MIT license, in which case the following will apply:
93
+
94
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
95
+ this software and associated documentation files (the "Software"), to deal in
96
+ the Software without restriction, including without limitation the rights to
97
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
98
+ of the Software, and to permit persons to whom the Software is furnished to do
99
+ so, subject to the following conditions:
100
+
101
+ The above copyright notice and this permission notice shall be included in all
102
+ copies or substantial portions of the Software.
103
+
104
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
105
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
106
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
107
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
108
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
109
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
110
+ SOFTWARE.
@@ -0,0 +1,208 @@
1
+ import { AbstractMapboxMapChild, AbstractMapboxMapChildProps } from "./AbstractMapboxMapChild.js";
2
+ import { MapboxClusterItem } from "./MapboxClusterItem.js";
3
+ import { BaseConfig, BaseProps } from "@studiometa/js-toolkit";
4
+ import { CircleLayerSpecification, GeoJSONSourceSpecification, Map, MapMouseEvent, SymbolLayerSpecification } from "mapbox-gl";
5
+ import { FeatureCollection, Point } from "geojson";
6
+
7
+ //#region MapboxCluster.d.ts
8
+ /**
9
+ * Document-level event a `MapboxCluster` dispatches when its instance mounts, so
10
+ * a `MapboxClusterItem` that mounted *before* its cluster can retry resolving it
11
+ * and register itself once the cluster is connected. The dispatching
12
+ * `MapboxCluster` instance travels in `detail`.
13
+ */
14
+ declare const MAPBOX_CLUSTER_CONNECTED = "mapbox-cluster:connected";
15
+ interface MapboxClusterProps extends AbstractMapboxMapChildProps {
16
+ $options: {
17
+ clusterMaxZoom: number;
18
+ clusterRadius: number;
19
+ clusterMinPoints: number;
20
+ clusterProperties: Record<string, unknown>;
21
+ clustersLayout: CircleLayerSpecification['layout'];
22
+ clustersPaint: CircleLayerSpecification['paint'];
23
+ clusterCountLayout: SymbolLayerSpecification['layout'];
24
+ clusterCountPaint: SymbolLayerSpecification['paint'];
25
+ unclusteredPointLayerType: string;
26
+ unclusteredPointLayout: Record<string, unknown>;
27
+ unclusteredPointPaint: Record<string, unknown>;
28
+ };
29
+ }
30
+ /**
31
+ * A clustered GeoJSON **source driver** whose features ARE its rendered items.
32
+ *
33
+ * `MapboxCluster` merges the map source and the sidebar list of a classic
34
+ * "store locator" into a single declarative unit: `MapboxClusterItem`s (rendered
35
+ * list entries living outside the map) push themselves into the cluster's
36
+ * registry, and the cluster derives its clustered GeoJSON source from that
37
+ * registry. Items self-register, the cluster rebuilds (debounced) on every
38
+ * registry change, gated on `whenMapReady`, and nothing observes or `$query`s.
39
+ *
40
+ * The cluster is deliberately **thin**: it owns only the map data and the
41
+ * clustering interaction (a clustered source, the three layers and the
42
+ * click-to-zoom on clusters). It does **not** select, fly to, filter by viewport
43
+ * or open popups — those search-UX concerns belong to the optional
44
+ * [`StoreLocator`](./StoreLocator.js) orchestrator, which drives them on top of a
45
+ * cluster. Used standalone, a `MapboxCluster` still renders a working clustered
46
+ * map + list (points render, clusters zoom on click); it simply reports a click
47
+ * on an unclustered point through the `map-item-click` event and lets the caller
48
+ * decide what it means.
49
+ *
50
+ * @see https://ui.studiometa.dev/reference/items/MapboxMap/
51
+ */
52
+ declare class MapboxCluster<T extends BaseProps = BaseProps> extends AbstractMapboxMapChild<T & MapboxClusterProps> {
53
+ /**
54
+ * Config.
55
+ */
56
+ static config: BaseConfig;
57
+ /**
58
+ * Unique base id for this instance.
59
+ * @private
60
+ */
61
+ __id: string;
62
+ /**
63
+ * Live registry of the mounted `MapboxClusterItem`s, in registration order.
64
+ * @private
65
+ */
66
+ __items: MapboxClusterItem[];
67
+ /**
68
+ * The registered `MapboxClusterItem`s, in registration order.
69
+ *
70
+ * Read-only surface for an orchestrator (e.g. `StoreLocator`) that needs to
71
+ * iterate the item set for viewport filtering, distance sorting or selection —
72
+ * the cluster owns the registry, consumers only read it. A defensive copy is
73
+ * returned so a consumer can not splice the live registry (which would corrupt
74
+ * click resolution and source generation without scheduling a rebuild).
75
+ */
76
+ get items(): readonly MapboxClusterItem[];
77
+ /**
78
+ * Derive an id for the given suffix from the instance base id.
79
+ * @private
80
+ * @param {string} suffix
81
+ * @returns {string}
82
+ */
83
+ __getId(suffix: string): string;
84
+ /**
85
+ * The GeoJSON `FeatureCollection` derived from the whole registered item set.
86
+ *
87
+ * This is the single source of truth pushed to the map source and only changes
88
+ * when the item set changes — panning must never rebuild it.
89
+ */
90
+ get featureCollection(): FeatureCollection<Point, Record<string, unknown>>;
91
+ /**
92
+ * Register an item and schedule a coalesced rebuild so a batch of
93
+ * registrations (e.g. a `Fetch` list swap) results in a single map update.
94
+ * @param {MapboxClusterItem} item
95
+ */
96
+ register(item: MapboxClusterItem): void;
97
+ /**
98
+ * Unregister an item and schedule a coalesced rebuild.
99
+ * @param {MapboxClusterItem} item
100
+ */
101
+ unregister(item: MapboxClusterItem): void;
102
+ /**
103
+ * Replace the live source data directly, bypassing the item registry.
104
+ *
105
+ * Kept for manual/imperative control; the common path is to let registered
106
+ * items drive the data. Safe to call before mount or after teardown.
107
+ *
108
+ * NOTE: this bypasses the registry-is-source invariant, so anything pushed
109
+ * here is transient — the next registry rebuild (any item mount/unmount, or a
110
+ * debounced `__scheduleRebuild`) derives the source from `featureCollection`
111
+ * again and silently overwrites it. Use it only for one-off imperative
112
+ * overlays that do not need to survive an item-set change.
113
+ *
114
+ * @param {GeoJSONSourceSpecification['data']} data
115
+ */
116
+ setData(data: GeoJSONSourceSpecification['data']): void;
117
+ /**
118
+ * Coalesce rebuilds into a single trailing call, so a batch of registrations
119
+ * spanning multiple ticks results in one map data update.
120
+ * @private
121
+ */
122
+ __scheduleRebuild: (...args: unknown[]) => void;
123
+ /**
124
+ * Push the derived feature collection to the source and announce the change.
125
+ * No-op until the map is ready (the initial build happens in `whenMapReady`).
126
+ * @private
127
+ */
128
+ __rebuild(): void;
129
+ /**
130
+ * Click handler for the clusters layer, zooming on the clicked cluster.
131
+ * @private
132
+ */
133
+ __handleClustersClick: (event: MapMouseEvent) => void;
134
+ /**
135
+ * Set the map canvas cursor, guarding against a missing map.
136
+ * @private
137
+ * @param {string} cursor
138
+ */
139
+ __setCursor(cursor: string): void;
140
+ /**
141
+ * Set a pointer cursor when entering the clusters layer.
142
+ * @private
143
+ */
144
+ __handleClustersMouseenter: () => void;
145
+ /**
146
+ * Reset the cursor when leaving the clusters layer.
147
+ * @private
148
+ */
149
+ __handleClustersMouseleave: () => void;
150
+ /**
151
+ * Report a click on an unclustered point: resolve the feature back to the
152
+ * registered item behind it and emit `map-item-click`. The cluster makes no
153
+ * decision about what a click means — an orchestrator (e.g. `StoreLocator`)
154
+ * listens and selects, opens a popup, etc.
155
+ * @private
156
+ */
157
+ __handleUnclusteredClick: (event: MapMouseEvent) => void;
158
+ /**
159
+ * Set a pointer cursor when entering an unclustered point.
160
+ * @private
161
+ */
162
+ __handleUnclusteredMouseenter: () => void;
163
+ /**
164
+ * Reset the cursor when leaving an unclustered point.
165
+ * @private
166
+ */
167
+ __handleUnclusteredMouseleave: () => void;
168
+ /**
169
+ * Mounted hook: build the source and layers, wire the clustering interaction
170
+ * and announce the initial item set — all once the map is ready.
171
+ */
172
+ mounted(): void;
173
+ /**
174
+ * Build the clustered source and its three layers and wire the clustering
175
+ * interaction — idempotently, so it can run both on first readiness and on a
176
+ * `style.load` re-injection after a `setStyle` wiped the style (H7, PR #567
177
+ * review).
178
+ *
179
+ * A `setStyle` clears sources and layers but leaves layer-scoped map listeners
180
+ * attached (they live on the map's event emitter, not the style), so this
181
+ * guards `addSource`/`addLayer` against an already-present resource and
182
+ * detaches every listener before re-attaching it — re-running never duplicates
183
+ * a listener nor throws a duplicate-id error.
184
+ * @private
185
+ * @param {Map} map
186
+ */
187
+ __inject(map: Map): void;
188
+ /**
189
+ * Detach every map-scoped listener wired in `mounted`.
190
+ * @private
191
+ * @param {Map} map
192
+ */
193
+ __offClusterListeners(map: Map): void;
194
+ /**
195
+ * Flush the per-layer listeners against the map being removed, while it is
196
+ * still referenceable — `__onDestroyed` runs later with `__readyMap` already
197
+ * cleared and could not reach the map to unsubscribe.
198
+ * @protected
199
+ * @param {Map} map
200
+ */
201
+ __onMapRemove(map: Map): void;
202
+ /**
203
+ * Teardown hook: tear down listeners, layers and source.
204
+ */
205
+ __onDestroyed(): void;
206
+ }
207
+ //#endregion
208
+ export { MAPBOX_CLUSTER_CONNECTED, MapboxCluster, MapboxCluster as default, MapboxClusterProps };