@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,53 @@
1
+ import { AbstractMapboxMapChild, AbstractMapboxMapChildProps } from "./AbstractMapboxMapChild.js";
2
+ import { BaseConfig, BaseProps } from "@studiometa/js-toolkit";
3
+ import { ControlPosition, IControl } from "mapbox-gl";
4
+
5
+ //#region AbstractMapboxControl.d.ts
6
+ interface AbstractMapboxControlProps extends AbstractMapboxMapChildProps {
7
+ $options: {
8
+ position: ControlPosition;
9
+ };
10
+ }
11
+ /**
12
+ * Base class for the Mapbox controls added to the map via `map.addControl`.
13
+ *
14
+ * It centralizes the shared `position` option, the lazy control instantiation
15
+ * and the add/remove lifecycle. Concrete controls only need to implement the
16
+ * `createControl` method to build their specific `mapboxgl.*Control` instance.
17
+ *
18
+ * @see https://ui.studiometa.dev/reference/items/MapboxMap/
19
+ */
20
+ declare class AbstractMapboxControl<T extends BaseProps = BaseProps> extends AbstractMapboxMapChild<T & AbstractMapboxControlProps> {
21
+ /**
22
+ * Config.
23
+ */
24
+ static config: BaseConfig;
25
+ /**
26
+ * Control instance.
27
+ * @private
28
+ */
29
+ __control: IControl;
30
+ /**
31
+ * The mapbox control instance.
32
+ */
33
+ get control(): IControl;
34
+ /**
35
+ * Create the concrete mapbox control instance.
36
+ *
37
+ * Subclasses must implement this method to return their specific
38
+ * `mapboxgl.*Control` instance built from the given options.
39
+ *
40
+ * @protected
41
+ */
42
+ createControl(_options: Record<string, unknown>): IControl;
43
+ /**
44
+ * Mounted hook.
45
+ */
46
+ mounted(): void;
47
+ /**
48
+ * Teardown hook.
49
+ */
50
+ __onDestroyed(): void;
51
+ }
52
+ //#endregion
53
+ export { AbstractMapboxControl, AbstractMapboxControl as default, AbstractMapboxControlProps };
@@ -0,0 +1,70 @@
1
+ import { AbstractMapboxMapChild } from "./AbstractMapboxMapChild.js";
2
+ //#region AbstractMapboxControl.ts
3
+ /**
4
+ * Base class for the Mapbox controls added to the map via `map.addControl`.
5
+ *
6
+ * It centralizes the shared `position` option, the lazy control instantiation
7
+ * and the add/remove lifecycle. Concrete controls only need to implement the
8
+ * `createControl` method to build their specific `mapboxgl.*Control` instance.
9
+ *
10
+ * @see https://ui.studiometa.dev/reference/items/MapboxMap/
11
+ */
12
+ var AbstractMapboxControl = class extends AbstractMapboxMapChild {
13
+ /**
14
+ * Config.
15
+ */
16
+ static config = {
17
+ name: "AbstractMapboxControl",
18
+ options: { position: {
19
+ type: String,
20
+ default: "top-right"
21
+ } }
22
+ };
23
+ /**
24
+ * Control instance.
25
+ * @private
26
+ */
27
+ __control;
28
+ /**
29
+ * The mapbox control instance.
30
+ */
31
+ get control() {
32
+ if (!this.__control) {
33
+ const { position: _position, name: _name, debug: _debug, log: _log, ...options } = this.$options;
34
+ this.__control = this.createControl(options);
35
+ }
36
+ return this.__control;
37
+ }
38
+ /**
39
+ * Create the concrete mapbox control instance.
40
+ *
41
+ * Subclasses must implement this method to return their specific
42
+ * `mapboxgl.*Control` instance built from the given options.
43
+ *
44
+ * @protected
45
+ */
46
+ createControl(_options) {
47
+ throw new Error("The `createControl` method must be implemented.");
48
+ }
49
+ /**
50
+ * Mounted hook.
51
+ */
52
+ mounted() {
53
+ this.whenMapReady((map) => {
54
+ map.addControl(this.control, this.$options.position);
55
+ });
56
+ }
57
+ /**
58
+ * Teardown hook.
59
+ */
60
+ __onDestroyed() {
61
+ if (this.__control) {
62
+ this.__readyMap?.removeControl(this.__control);
63
+ this.__control = void 0;
64
+ }
65
+ }
66
+ };
67
+ //#endregion
68
+ export { AbstractMapboxControl, AbstractMapboxControl as default };
69
+
70
+ //# sourceMappingURL=AbstractMapboxControl.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AbstractMapboxControl.js","names":[],"sources":["../AbstractMapboxControl.ts"],"sourcesContent":["import { type BaseProps, type BaseConfig } from '@studiometa/js-toolkit';\nimport type { ControlPosition, IControl } from 'mapbox-gl';\nimport {\n AbstractMapboxMapChild,\n type AbstractMapboxMapChildProps,\n} from './AbstractMapboxMapChild.js';\n\nexport interface AbstractMapboxControlProps extends AbstractMapboxMapChildProps {\n $options: {\n position: ControlPosition;\n };\n}\n\n/**\n * Base class for the Mapbox controls added to the map via `map.addControl`.\n *\n * It centralizes the shared `position` option, the lazy control instantiation\n * and the add/remove lifecycle. Concrete controls only need to implement the\n * `createControl` method to build their specific `mapboxgl.*Control` instance.\n *\n * @see https://ui.studiometa.dev/reference/items/MapboxMap/\n */\nexport class AbstractMapboxControl<T extends BaseProps = BaseProps> extends AbstractMapboxMapChild<\n T & AbstractMapboxControlProps\n> {\n /**\n * Config.\n */\n static config: BaseConfig = {\n name: 'AbstractMapboxControl',\n options: {\n position: {\n type: String,\n default: 'top-right',\n },\n },\n };\n\n /**\n * Control instance.\n * @private\n */\n __control: IControl;\n\n /**\n * The mapbox control instance.\n */\n get control() {\n if (!this.__control) {\n const {\n position: _position,\n name: _name,\n debug: _debug,\n log: _log,\n ...options\n } = this.$options;\n this.__control = this.createControl(options);\n }\n\n return this.__control;\n }\n\n /**\n * Create the concrete mapbox control instance.\n *\n * Subclasses must implement this method to return their specific\n * `mapboxgl.*Control` instance built from the given options.\n *\n * @protected\n */\n createControl(_options: Record<string, unknown>): IControl {\n throw new Error('The `createControl` method must be implemented.');\n }\n\n /**\n * Mounted hook.\n */\n mounted() {\n this.whenMapReady((map) => {\n map.addControl(this.control, this.$options.position);\n });\n }\n\n /**\n * Teardown hook.\n */\n __onDestroyed() {\n if (this.__control) {\n this.__readyMap?.removeControl(this.__control);\n this.__control = undefined;\n }\n }\n}\n\nexport default AbstractMapboxControl;\n"],"mappings":";;;;;;;;;;;AAsBA,IAAa,wBAAb,cAA4E,uBAE1E;;;;CAIA,OAAO,SAAqB;EAC1B,MAAM;EACN,SAAS,EACP,UAAU;GACR,MAAM;GACN,SAAS;GACV,EACF;EACF;;;;;CAMD;;;;CAKA,IAAI,UAAU;AACZ,MAAI,CAAC,KAAK,WAAW;GACnB,MAAM,EACJ,UAAU,WACV,MAAM,OACN,OAAO,QACP,KAAK,MACL,GAAG,YACD,KAAK;AACT,QAAK,YAAY,KAAK,cAAc,QAAQ;;AAG9C,SAAO,KAAK;;;;;;;;;;CAWd,cAAc,UAA6C;AACzD,QAAM,IAAI,MAAM,kDAAkD;;;;;CAMpE,UAAU;AACR,OAAK,cAAc,QAAQ;AACzB,OAAI,WAAW,KAAK,SAAS,KAAK,SAAS,SAAS;IACpD;;;;;CAMJ,gBAAgB;AACd,MAAI,KAAK,WAAW;AAClB,QAAK,YAAY,cAAc,KAAK,UAAU;AAC9C,QAAK,YAAY,KAAA"}
@@ -0,0 +1,229 @@
1
+ import { MapboxMap } from "./MapboxMap.js";
2
+ import { Base, BaseConfig, BaseProps } from "@studiometa/js-toolkit";
3
+ import { Map } from "mapbox-gl";
4
+
5
+ //#region AbstractMapboxMapChild.d.ts
6
+ interface AbstractMapboxMapChildProps extends BaseProps {}
7
+ /**
8
+ * Document-level event a `MapboxMap` dispatches when its instance mounts, so a
9
+ * child that mounted *before* its map (e.g. an eagerly registered child under a
10
+ * lazily imported map) can retry resolving its parent and inject itself once the
11
+ * map is connected. The dispatching `MapboxMap` instance travels in `detail`.
12
+ */
13
+ declare const MAPBOX_MAP_CONNECTED = "mapbox-map:connected";
14
+ /**
15
+ * Base class for every component living inside a `MapboxMap`.
16
+ *
17
+ * Children are self-sufficient and dynamic-DOM-native: they resolve their
18
+ * parent `MapboxMap` on their own via `$closest`, wait for the map to be ready
19
+ * with `whenMapReady`, then inject their contribution. Each component is
20
+ * registered independently (e.g. with `registerComponent`, optionally behind a
21
+ * lazy `importWhen*` helper); registration order does not matter because a child
22
+ * resolves its map through the connected-event retry. Once registered,
23
+ * js-toolkit's document-wide `MutationObserver` mounts them whenever their
24
+ * element enters the DOM —
25
+ * statically, `Fetch`-injected or `appendChild`-ed — and terminates them when it
26
+ * leaves, at which point they remove their contribution again.
27
+ *
28
+ * The base hardens three things every child inherits, rather than relying on
29
+ * per-subclass discipline:
30
+ *
31
+ * 1. **Guarded injection & teardown** — mapbox-gl throws readily (a duplicate
32
+ * source id, any style-touching call after `map.remove()`), and js-toolkit's
33
+ * global queue runs lifecycle hooks with no try/catch: a single synchronous
34
+ * throw wedges the queue and freezes every mount/destroy on the page. The
35
+ * ready callback and the subclass teardown (`__onDestroyed`) are both run
36
+ * inside a try/catch that routes to `$warn` + a `map-error` event and never
37
+ * rethrows.
38
+ * 2. **Dead-map safety** — once ready, the child subscribes to the map's own
39
+ * `remove` event; when it fires the cached map reference is dropped so no
40
+ * teardown ever calls a method on a removed map (which throws `TypeError`).
41
+ * 3. **Retryable, standing resolution** — resolution is not one-shot: a child
42
+ * with no map yet waits for `MAPBOX_MAP_CONNECTED`, and a map destroy →
43
+ * remount re-injects the child on the new map's next load.
44
+ * 4. **Style-reload re-injection** — a `map.setStyle()` wipes the whole style
45
+ * (every source/layer/sprite) while the map instance and the still-mounted
46
+ * children survive, so the declarative resources would silently vanish. Once
47
+ * ready, the child subscribes to the map's `style.load` — fired once per
48
+ * style load, the Mapbox-recommended hook for re-adding custom sources/layers
49
+ * when switching base style — and re-runs its injection so it re-adds its
50
+ * contribution onto the fresh style (H7, PR #567 review). The re-run reuses
51
+ * the same containment as the first injection and is guarded on the resource
52
+ * already being present, so it never double-injects.
53
+ *
54
+ * @see https://ui.studiometa.dev/reference/items/MapboxMap/
55
+ */
56
+ declare class AbstractMapboxMapChild<T extends BaseProps = BaseProps> extends Base<T & AbstractMapboxMapChildProps> {
57
+ /**
58
+ * Config.
59
+ */
60
+ static config: BaseConfig;
61
+ /**
62
+ * The parent `MapboxMap` resolved at ready-time.
63
+ *
64
+ * `destroyed()` runs *after* the element has been detached from the DOM (e.g.
65
+ * a `Fetch` list swap, or the parent map itself being removed), and a
66
+ * `$closest` lookup on a disconnected node returns nothing — a real bug that
67
+ * would leave the child's contribution stuck on the map. Caching the resolved
68
+ * references at ready-time keeps every teardown path working through the
69
+ * detach.
70
+ * @private
71
+ */
72
+ __readyMapboxMap?: MapboxMap;
73
+ /**
74
+ * The Mapbox `Map` instance resolved at ready-time, cached for teardown. It is
75
+ * dropped as soon as the map's `remove` event fires so teardown never touches
76
+ * a removed map.
77
+ * @private
78
+ */
79
+ __readyMap?: Map;
80
+ /**
81
+ * The injection callback registered through `whenMapReady`, kept so it can be
82
+ * re-run against a new map when the current one is destroyed and remounted.
83
+ *
84
+ * The callback may be synchronous or `async`: a returned promise is awaited
85
+ * inside the same containment as a synchronous body, so a rejection routes to
86
+ * `$warn` + the `map-error` event instead of surfacing as an unhandled rejection.
87
+ * @private
88
+ */
89
+ __readyCallback?: (map: Map) => void | Promise<void>;
90
+ /**
91
+ * Off handler for a still-pending `map-load` subscription, flushed on destroy
92
+ * so a child removed before the map finished loading leaves no listener behind.
93
+ * @private
94
+ */
95
+ __offMapReady?: () => void;
96
+ /**
97
+ * Off handler for the ready map's `remove` subscription.
98
+ * @private
99
+ */
100
+ __offMapRemove?: () => void;
101
+ /**
102
+ * Off handler for the ready map's `style.load` re-injection subscription.
103
+ * @private
104
+ */
105
+ __offStyleReload?: () => void;
106
+ /**
107
+ * Off handler for the document-level `MAPBOX_MAP_CONNECTED` retry subscription.
108
+ * @private
109
+ */
110
+ __offConnected?: () => void;
111
+ /**
112
+ * The closest parent `MapboxMap` component instance.
113
+ */
114
+ get mapboxMap(): MapboxMap<BaseProps>;
115
+ /**
116
+ * The Mapbox `Map` instance of the closest parent `MapboxMap` component.
117
+ */
118
+ get map(): Map;
119
+ /**
120
+ * Run a callback once the parent map is ready — now, on the next `map-load`,
121
+ * or once a `MapboxMap` connects if none exists yet.
122
+ *
123
+ * The callback is stored so it can be re-run on a fresh map after a destroy →
124
+ * remount. It is wrapped so a throw never propagates into the global queue, is
125
+ * never fired after the child has been destroyed, and the resolved
126
+ * map/`MapboxMap` are cached before it runs so teardown can reach them even
127
+ * once the element is detached.
128
+ *
129
+ * The callback may be `async`: a subclass that awaits (image loading, cluster
130
+ * expansion, ...) must additionally guard against the map changing under it by
131
+ * checking `this.__readyMap === map` after every `await`, since the map it was
132
+ * handed can be removed — or replaced by another — while the promise is in
133
+ * flight. A rejected promise is contained here, never rethrown.
134
+ *
135
+ * @param {(map: Map) => void | Promise<void>} cb The work to run against the ready map.
136
+ */
137
+ whenMapReady(cb: (map: Map) => void | Promise<void>): void;
138
+ /**
139
+ * Resolve the parent `MapboxMap` and bind to it, or wait for one to connect.
140
+ * @private
141
+ */
142
+ __resolveMap(): void;
143
+ /**
144
+ * Subscribe once to `MAPBOX_MAP_CONNECTED` and retry resolution when a map
145
+ * whose element is an ancestor of this child connects.
146
+ * @private
147
+ */
148
+ __waitForConnectedMap(): void;
149
+ /**
150
+ * Bind to a resolved `MapboxMap`: run the ready callback now if its map is
151
+ * already loaded, otherwise once on `map-load`.
152
+ * @private
153
+ * @param {MapboxMap} mapboxMap
154
+ */
155
+ __bindToMap(mapboxMap: MapboxMap): void;
156
+ /**
157
+ * Run the ready callback inside a uniform containment for both synchronous
158
+ * throws and rejected promises: a synchronous body is wrapped in `try/catch`,
159
+ * and an `async` body's returned promise is awaited so its rejection routes to
160
+ * `$warn` + the `map-error` event instead of becoming an unhandled rejection.
161
+ * Neither path ever rethrows into the global lifecycle queue.
162
+ * @private
163
+ * @param {Map} map
164
+ */
165
+ __runReadyCallback(map: Map): void;
166
+ /**
167
+ * Subscribe once to the map's own `remove` event so teardown never runs
168
+ * against a removed map, and so the child re-injects on a remounted map.
169
+ * @private
170
+ * @param {Map} map
171
+ */
172
+ __bindMapRemove(map: Map): void;
173
+ /**
174
+ * Subscribe to the map's `style.load` so the child re-runs its injection after
175
+ * a `setStyle` replaces the whole style, re-adding the source/layer/sprite it
176
+ * would otherwise have silently lost.
177
+ *
178
+ * `style.load` fires once per style load — Mapbox's own recommended hook for
179
+ * re-adding custom sources and layers when switching base style — so it does
180
+ * not need the `styledata` de-duplication a broader `styledata` handler would.
181
+ * The handler bails until the child has actually finished its first injection
182
+ * on this map (`__readyMap === map`): at the *initial* style load `__readyMap`
183
+ * is not set yet (the first injection runs on `map-load`), so this never
184
+ * double-injects on mount and only re-injects on a genuine later `setStyle`.
185
+ * @private
186
+ * @param {Map} map
187
+ */
188
+ __bindStyleReload(map: Map): void;
189
+ /**
190
+ * Contain an error raised by a guarded injection or teardown: warn and emit an
191
+ * `map-error` event, but never rethrow into the global queue.
192
+ * @private
193
+ * @param {unknown} err
194
+ */
195
+ __handleError(err: unknown): void;
196
+ /**
197
+ * Hook run when the ready map fires its own `remove` event, while the map is
198
+ * still referenceable (before `__readyMap` is cleared).
199
+ *
200
+ * Subclasses that attach map-scoped listeners (a layer waiting on
201
+ * `sourcedata`, a cluster's per-layer click/hover handlers) override this to
202
+ * `off` them against the map they were bound to — the removed map — since
203
+ * their `__onDestroyed` runs later with `__readyMap` already `undefined` and
204
+ * could not reach the map to unsubscribe.
205
+ * @protected
206
+ * @param {Map} _map The map being removed.
207
+ */
208
+ __onMapRemove(_map: Map): void;
209
+ /**
210
+ * Teardown hook implemented by subclasses instead of `destroyed()`.
211
+ *
212
+ * It runs inside the base's guard (see `destroyed`) so a throwing teardown — a
213
+ * style-touching mapbox call, most often — can never wedge the global queue.
214
+ * Implementations read the cached `__readyMap`, which is already `undefined`
215
+ * when the map has been removed, and must not call `super`.
216
+ * @protected
217
+ */
218
+ __onDestroyed(): void;
219
+ /**
220
+ * Destroyed hook.
221
+ *
222
+ * Runs the guarded subclass teardown, then flushes every base subscription
223
+ * (`map-load`, the map's `remove`, the connected retry). Subclasses override
224
+ * `__onDestroyed` rather than this method.
225
+ */
226
+ destroyed(): void;
227
+ }
228
+ //#endregion
229
+ export { AbstractMapboxMapChild, AbstractMapboxMapChild as default, AbstractMapboxMapChildProps, MAPBOX_MAP_CONNECTED };
@@ -0,0 +1,336 @@
1
+ import { Base } from "@studiometa/js-toolkit";
2
+ //#region AbstractMapboxMapChild.ts
3
+ /**
4
+ * Document-level event a `MapboxMap` dispatches when its instance mounts, so a
5
+ * child that mounted *before* its map (e.g. an eagerly registered child under a
6
+ * lazily imported map) can retry resolving its parent and inject itself once the
7
+ * map is connected. The dispatching `MapboxMap` instance travels in `detail`.
8
+ */
9
+ const MAPBOX_MAP_CONNECTED = "mapbox-map:connected";
10
+ /**
11
+ * Base class for every component living inside a `MapboxMap`.
12
+ *
13
+ * Children are self-sufficient and dynamic-DOM-native: they resolve their
14
+ * parent `MapboxMap` on their own via `$closest`, wait for the map to be ready
15
+ * with `whenMapReady`, then inject their contribution. Each component is
16
+ * registered independently (e.g. with `registerComponent`, optionally behind a
17
+ * lazy `importWhen*` helper); registration order does not matter because a child
18
+ * resolves its map through the connected-event retry. Once registered,
19
+ * js-toolkit's document-wide `MutationObserver` mounts them whenever their
20
+ * element enters the DOM —
21
+ * statically, `Fetch`-injected or `appendChild`-ed — and terminates them when it
22
+ * leaves, at which point they remove their contribution again.
23
+ *
24
+ * The base hardens three things every child inherits, rather than relying on
25
+ * per-subclass discipline:
26
+ *
27
+ * 1. **Guarded injection & teardown** — mapbox-gl throws readily (a duplicate
28
+ * source id, any style-touching call after `map.remove()`), and js-toolkit's
29
+ * global queue runs lifecycle hooks with no try/catch: a single synchronous
30
+ * throw wedges the queue and freezes every mount/destroy on the page. The
31
+ * ready callback and the subclass teardown (`__onDestroyed`) are both run
32
+ * inside a try/catch that routes to `$warn` + a `map-error` event and never
33
+ * rethrows.
34
+ * 2. **Dead-map safety** — once ready, the child subscribes to the map's own
35
+ * `remove` event; when it fires the cached map reference is dropped so no
36
+ * teardown ever calls a method on a removed map (which throws `TypeError`).
37
+ * 3. **Retryable, standing resolution** — resolution is not one-shot: a child
38
+ * with no map yet waits for `MAPBOX_MAP_CONNECTED`, and a map destroy →
39
+ * remount re-injects the child on the new map's next load.
40
+ * 4. **Style-reload re-injection** — a `map.setStyle()` wipes the whole style
41
+ * (every source/layer/sprite) while the map instance and the still-mounted
42
+ * children survive, so the declarative resources would silently vanish. Once
43
+ * ready, the child subscribes to the map's `style.load` — fired once per
44
+ * style load, the Mapbox-recommended hook for re-adding custom sources/layers
45
+ * when switching base style — and re-runs its injection so it re-adds its
46
+ * contribution onto the fresh style (H7, PR #567 review). The re-run reuses
47
+ * the same containment as the first injection and is guarded on the resource
48
+ * already being present, so it never double-injects.
49
+ *
50
+ * @see https://ui.studiometa.dev/reference/items/MapboxMap/
51
+ */
52
+ var AbstractMapboxMapChild = class extends Base {
53
+ /**
54
+ * Config.
55
+ */
56
+ static config = {
57
+ name: "AbstractMapboxMapChild",
58
+ emits: ["map-error"]
59
+ };
60
+ /**
61
+ * The parent `MapboxMap` resolved at ready-time.
62
+ *
63
+ * `destroyed()` runs *after* the element has been detached from the DOM (e.g.
64
+ * a `Fetch` list swap, or the parent map itself being removed), and a
65
+ * `$closest` lookup on a disconnected node returns nothing — a real bug that
66
+ * would leave the child's contribution stuck on the map. Caching the resolved
67
+ * references at ready-time keeps every teardown path working through the
68
+ * detach.
69
+ * @private
70
+ */
71
+ __readyMapboxMap;
72
+ /**
73
+ * The Mapbox `Map` instance resolved at ready-time, cached for teardown. It is
74
+ * dropped as soon as the map's `remove` event fires so teardown never touches
75
+ * a removed map.
76
+ * @private
77
+ */
78
+ __readyMap;
79
+ /**
80
+ * The injection callback registered through `whenMapReady`, kept so it can be
81
+ * re-run against a new map when the current one is destroyed and remounted.
82
+ *
83
+ * The callback may be synchronous or `async`: a returned promise is awaited
84
+ * inside the same containment as a synchronous body, so a rejection routes to
85
+ * `$warn` + the `map-error` event instead of surfacing as an unhandled rejection.
86
+ * @private
87
+ */
88
+ __readyCallback;
89
+ /**
90
+ * Off handler for a still-pending `map-load` subscription, flushed on destroy
91
+ * so a child removed before the map finished loading leaves no listener behind.
92
+ * @private
93
+ */
94
+ __offMapReady;
95
+ /**
96
+ * Off handler for the ready map's `remove` subscription.
97
+ * @private
98
+ */
99
+ __offMapRemove;
100
+ /**
101
+ * Off handler for the ready map's `style.load` re-injection subscription.
102
+ * @private
103
+ */
104
+ __offStyleReload;
105
+ /**
106
+ * Off handler for the document-level `MAPBOX_MAP_CONNECTED` retry subscription.
107
+ * @private
108
+ */
109
+ __offConnected;
110
+ /**
111
+ * The closest parent `MapboxMap` component instance.
112
+ */
113
+ get mapboxMap() {
114
+ const mapboxMap = this.$closest("MapboxMap");
115
+ if (!mapboxMap) this.$warn("Can not find the parent map, does this component has a parent MapboxMap component?");
116
+ return mapboxMap;
117
+ }
118
+ /**
119
+ * The Mapbox `Map` instance of the closest parent `MapboxMap` component.
120
+ */
121
+ get map() {
122
+ return this.mapboxMap?.map;
123
+ }
124
+ /**
125
+ * Run a callback once the parent map is ready — now, on the next `map-load`,
126
+ * or once a `MapboxMap` connects if none exists yet.
127
+ *
128
+ * The callback is stored so it can be re-run on a fresh map after a destroy →
129
+ * remount. It is wrapped so a throw never propagates into the global queue, is
130
+ * never fired after the child has been destroyed, and the resolved
131
+ * map/`MapboxMap` are cached before it runs so teardown can reach them even
132
+ * once the element is detached.
133
+ *
134
+ * The callback may be `async`: a subclass that awaits (image loading, cluster
135
+ * expansion, ...) must additionally guard against the map changing under it by
136
+ * checking `this.__readyMap === map` after every `await`, since the map it was
137
+ * handed can be removed — or replaced by another — while the promise is in
138
+ * flight. A rejected promise is contained here, never rethrown.
139
+ *
140
+ * @param {(map: Map) => void | Promise<void>} cb The work to run against the ready map.
141
+ */
142
+ whenMapReady(cb) {
143
+ this.__readyCallback = cb;
144
+ this.__resolveMap();
145
+ }
146
+ /**
147
+ * Resolve the parent `MapboxMap` and bind to it, or wait for one to connect.
148
+ * @private
149
+ */
150
+ __resolveMap() {
151
+ const mapboxMap = this.$closest("MapboxMap");
152
+ if (!mapboxMap) {
153
+ this.__waitForConnectedMap();
154
+ return;
155
+ }
156
+ this.__bindToMap(mapboxMap);
157
+ }
158
+ /**
159
+ * Subscribe once to `MAPBOX_MAP_CONNECTED` and retry resolution when a map
160
+ * whose element is an ancestor of this child connects.
161
+ * @private
162
+ */
163
+ __waitForConnectedMap() {
164
+ if (this.__offConnected) return;
165
+ const handler = (event) => {
166
+ if (!event.detail?.$el?.contains(this.$el)) return;
167
+ this.__offConnected?.();
168
+ this.__offConnected = void 0;
169
+ this.__resolveMap();
170
+ };
171
+ document.addEventListener(MAPBOX_MAP_CONNECTED, handler);
172
+ this.__offConnected = () => document.removeEventListener(MAPBOX_MAP_CONNECTED, handler);
173
+ }
174
+ /**
175
+ * Bind to a resolved `MapboxMap`: run the ready callback now if its map is
176
+ * already loaded, otherwise once on `map-load`.
177
+ * @private
178
+ * @param {MapboxMap} mapboxMap
179
+ */
180
+ __bindToMap(mapboxMap) {
181
+ const map = mapboxMap.map;
182
+ if (!map) {
183
+ this.__waitForConnectedMap();
184
+ return;
185
+ }
186
+ this.__offMapReady?.();
187
+ this.__offMapReady = void 0;
188
+ this.__bindMapRemove(map);
189
+ this.__bindStyleReload(map);
190
+ const run = () => {
191
+ if (!this.$isMounted) return;
192
+ this.__readyMapboxMap = mapboxMap;
193
+ this.__readyMap = map;
194
+ this.__runReadyCallback(map);
195
+ };
196
+ if (mapboxMap.isLoaded) run();
197
+ else this.__offMapReady = mapboxMap.$on("map-load", () => {
198
+ this.__offMapReady = void 0;
199
+ run();
200
+ }, { once: true });
201
+ }
202
+ /**
203
+ * Run the ready callback inside a uniform containment for both synchronous
204
+ * throws and rejected promises: a synchronous body is wrapped in `try/catch`,
205
+ * and an `async` body's returned promise is awaited so its rejection routes to
206
+ * `$warn` + the `map-error` event instead of becoming an unhandled rejection.
207
+ * Neither path ever rethrows into the global lifecycle queue.
208
+ * @private
209
+ * @param {Map} map
210
+ */
211
+ __runReadyCallback(map) {
212
+ let result;
213
+ try {
214
+ result = this.__readyCallback?.(map);
215
+ } catch (err) {
216
+ this.__handleError(err);
217
+ return;
218
+ }
219
+ if (result && typeof result.then === "function") Promise.resolve(result).catch((err) => this.__handleError(err));
220
+ }
221
+ /**
222
+ * Subscribe once to the map's own `remove` event so teardown never runs
223
+ * against a removed map, and so the child re-injects on a remounted map.
224
+ * @private
225
+ * @param {Map} map
226
+ */
227
+ __bindMapRemove(map) {
228
+ this.__offMapRemove?.();
229
+ this.__offMapRemove = void 0;
230
+ if (typeof map?.on !== "function") return;
231
+ const handler = () => {
232
+ this.__offMapRemove?.();
233
+ this.__offMapRemove = void 0;
234
+ try {
235
+ this.__onMapRemove(map);
236
+ } catch (err) {
237
+ this.__handleError(err);
238
+ }
239
+ this.__offMapReady?.();
240
+ this.__offMapReady = void 0;
241
+ this.__offStyleReload?.();
242
+ this.__offStyleReload = void 0;
243
+ this.__readyMap = void 0;
244
+ this.__readyMapboxMap = void 0;
245
+ if (this.$isMounted && this.__readyCallback) this.__waitForConnectedMap();
246
+ };
247
+ map.on("remove", handler);
248
+ this.__offMapRemove = () => map.off("remove", handler);
249
+ }
250
+ /**
251
+ * Subscribe to the map's `style.load` so the child re-runs its injection after
252
+ * a `setStyle` replaces the whole style, re-adding the source/layer/sprite it
253
+ * would otherwise have silently lost.
254
+ *
255
+ * `style.load` fires once per style load — Mapbox's own recommended hook for
256
+ * re-adding custom sources and layers when switching base style — so it does
257
+ * not need the `styledata` de-duplication a broader `styledata` handler would.
258
+ * The handler bails until the child has actually finished its first injection
259
+ * on this map (`__readyMap === map`): at the *initial* style load `__readyMap`
260
+ * is not set yet (the first injection runs on `map-load`), so this never
261
+ * double-injects on mount and only re-injects on a genuine later `setStyle`.
262
+ * @private
263
+ * @param {Map} map
264
+ */
265
+ __bindStyleReload(map) {
266
+ this.__offStyleReload?.();
267
+ this.__offStyleReload = void 0;
268
+ if (typeof map?.on !== "function") return;
269
+ const handler = () => {
270
+ if (!this.$isMounted || !this.__readyCallback || this.__readyMap !== map) return;
271
+ this.__runReadyCallback(map);
272
+ };
273
+ map.on("style.load", handler);
274
+ this.__offStyleReload = () => map.off("style.load", handler);
275
+ }
276
+ /**
277
+ * Contain an error raised by a guarded injection or teardown: warn and emit an
278
+ * `map-error` event, but never rethrow into the global queue.
279
+ * @private
280
+ * @param {unknown} err
281
+ */
282
+ __handleError(err) {
283
+ this.$warn(err);
284
+ this.$emit("map-error", err);
285
+ }
286
+ /**
287
+ * Hook run when the ready map fires its own `remove` event, while the map is
288
+ * still referenceable (before `__readyMap` is cleared).
289
+ *
290
+ * Subclasses that attach map-scoped listeners (a layer waiting on
291
+ * `sourcedata`, a cluster's per-layer click/hover handlers) override this to
292
+ * `off` them against the map they were bound to — the removed map — since
293
+ * their `__onDestroyed` runs later with `__readyMap` already `undefined` and
294
+ * could not reach the map to unsubscribe.
295
+ * @protected
296
+ * @param {Map} _map The map being removed.
297
+ */
298
+ __onMapRemove(_map) {}
299
+ /**
300
+ * Teardown hook implemented by subclasses instead of `destroyed()`.
301
+ *
302
+ * It runs inside the base's guard (see `destroyed`) so a throwing teardown — a
303
+ * style-touching mapbox call, most often — can never wedge the global queue.
304
+ * Implementations read the cached `__readyMap`, which is already `undefined`
305
+ * when the map has been removed, and must not call `super`.
306
+ * @protected
307
+ */
308
+ __onDestroyed() {}
309
+ /**
310
+ * Destroyed hook.
311
+ *
312
+ * Runs the guarded subclass teardown, then flushes every base subscription
313
+ * (`map-load`, the map's `remove`, the connected retry). Subclasses override
314
+ * `__onDestroyed` rather than this method.
315
+ */
316
+ destroyed() {
317
+ try {
318
+ this.__onDestroyed();
319
+ } catch (err) {
320
+ this.__handleError(err);
321
+ }
322
+ this.__offMapReady?.();
323
+ this.__offMapReady = void 0;
324
+ this.__offMapRemove?.();
325
+ this.__offMapRemove = void 0;
326
+ this.__offStyleReload?.();
327
+ this.__offStyleReload = void 0;
328
+ this.__offConnected?.();
329
+ this.__offConnected = void 0;
330
+ this.__readyCallback = void 0;
331
+ }
332
+ };
333
+ //#endregion
334
+ export { AbstractMapboxMapChild, AbstractMapboxMapChild as default, MAPBOX_MAP_CONNECTED };
335
+
336
+ //# sourceMappingURL=AbstractMapboxMapChild.js.map