@dereekb/dbx-web 13.40.0 → 13.42.0

package/mapbox/README.md

@@ -3,4 +3,53 @@
 
 The sources for this package are in the main [@dereekb/dbx-components](https://github.com/dereekb/dbx-components) repo. Please file issues and pull requests against that repo.
 
+## Required build asset: the mapbox-gl web worker
+
+Apps using `provideDbxMapbox()` must copy mapbox-gl's prebuilt CSP web worker into their
+assets. Add this entry to the `assets` array of the app's `build` target in `project.json`:
+
+```json
+{
+  "input": "node_modules/mapbox-gl/dist",
+  "glob": "mapbox-gl-csp-worker.js",
+  "output": "assets/mapbox-gl"
+}
+```
+
+`provideDbxMapbox()` registers an app initializer that points `mapboxgl.workerUrl` at
+`assets/mapbox-gl/mapbox-gl-csp-worker.js` before any map is created, and logs an error
+naming this snippet if the asset is not reachable.
+
+### Why
+
+mapbox-gl builds its web worker by stringifying two of its own functions into a `Blob`.
+Only those function *bodies* are serialized, so anything the bundler hoists to module scope
+is missing inside the worker. `@angular/build` unconditionally disables esbuild's
+`object-rest-spread` support (a V8 performance workaround, still present in Angular 22), which
+rewrites every object spread into exactly such a hoisted helper. From mapbox-gl **3.26.0** on
+there are object spreads in the serialized worker code, so the worker dies while loading tiles:
+
+```
+ReferenceError: __spreadValues is not defined   at Ie.loadTile
+```
+
+(In a production build the helper name is minified, so the same failure reads as
+`ReferenceError: <mangled> is not defined`.)
+
+Loading the worker from a real file instead of the generated blob — mapbox's own documented
+`workerUrl` escape hatch — avoids the problem entirely at any mapbox-gl version. Copying the
+asset out of the app's own `node_modules` keeps the worker in version lockstep with the
+`mapbox-gl` the app bundles.
+
+### Options
+
+`provideDbxMapbox({ worker })` accepts:
+
+- `workerUrl` — serve the asset from somewhere other than the default path.
+- `enabled: false` — restore mapbox-gl's stock blob worker. Only safe below mapbox-gl 3.26.0.
+
+Note the CSP worker does not support the dynamically loaded RTL text plugin
+(`setRTLTextPlugin`) or `addTileProvider` modules, which rely on a hook the blob worker
+provides. Apps needing those must set `enabled: false` and stay below mapbox-gl 3.26.0.
+
 License: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-web",
-  "version": "13.40.0",
+  "version": "13.42.0",
   "sideEffects": [
     "*.scss",
     "*.css"
@@ -13,12 +13,12 @@
     "@angular/material": "^21.2.9",
     "@angular/platform-browser": "21.2.11",
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/browser": "13.40.0",
-    "@dereekb/date": "13.40.0",
-    "@dereekb/dbx-core": "13.40.0",
-    "@dereekb/rxjs": "13.40.0",
-    "@dereekb/util": "13.40.0",
-    "@dereekb/vitest": "13.40.0",
+    "@dereekb/browser": "13.42.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/dbx-core": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
+    "@dereekb/vitest": "13.42.0",
     "@ngbracket/ngx-layout": "^21.0.0",
     "@ngrx/component-store": "^21.1.0",
     "@ngrx/effects": "^21.1.0",

package/types/dereekb-dbx-web-mapbox.d.ts

@@ -759,16 +759,98 @@ declare class DbxMapboxModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<DbxMapboxModule>;
 }
 
+/**
+ * Relative url the mapbox-gl CSP web worker asset is expected to be served from.
+ *
+ * The asset itself is copied out of `node_modules/mapbox-gl/dist/mapbox-gl-csp-worker.js`
+ * by the consuming app's build configuration, which keeps it in version lockstep with the
+ * `mapbox-gl` the app actually bundles.
+ */
+declare const DEFAULT_DBX_MAPBOX_WORKER_URL = "assets/mapbox-gl/mapbox-gl-csp-worker.js";
+/**
+ * Configuration for {@link configureDbxMapboxWorker}.
+ */
+interface DbxMapboxWorkerConfig {
+    /**
+     * Whether or not to load mapbox-gl's web worker from a self-hosted asset instead of the
+     * default blob url.
+     *
+     * True by default. Set to false only to restore mapbox-gl's stock blob worker, which is
+     * broken in Angular/esbuild apps on mapbox-gl 3.26.0 and up.
+     */
+    readonly enabled?: Maybe<boolean>;
+    /**
+     * Url the mapbox-gl CSP web worker asset is served from.
+     *
+     * Defaults to {@link DEFAULT_DBX_MAPBOX_WORKER_URL}.
+     */
+    readonly workerUrl?: Maybe<string>;
+}
+/**
+ * Result of {@link configureDbxMapboxWorker}.
+ */
+interface DbxMapboxWorkerConfigurationResult {
+    /**
+     * Whether or not the self-hosted worker was configured on mapbox-gl.
+     */
+    readonly configured: boolean;
+    /**
+     * Url that was configured, if any.
+     */
+    readonly workerUrl: Maybe<string>;
+    /**
+     * Whether or not the configured worker asset could be retrieved.
+     *
+     * Null when no check was performed.
+     */
+    readonly available: Maybe<boolean>;
+}
+/**
+ * Checks whether the mapbox-gl web worker asset is actually served from the given url.
+ *
+ * @param workerUrl - Url the worker asset is expected at.
+ * @returns True when the asset responds successfully.
+ */
+declare function isDbxMapboxWorkerAssetAvailable(workerUrl: string): Promise<boolean>;
+/**
+ * Configures mapbox-gl to load its web worker from a self-hosted copy of mapbox's prebuilt
+ * CSP worker rather than from the blob url it generates itself.
+ *
+ * mapbox-gl's default worker is built by stringifying two of its own functions into a blob.
+ * Only those function bodies are serialized, so any helper the bundler hoists to module
+ * scope is missing at runtime. `@angular/build` unconditionally disables esbuild's
+ * `object-rest-spread` support, which rewrites every object spread in mapbox-gl 3.26.0+ into
+ * exactly such a hoisted helper, and the worker then dies with a `ReferenceError` while
+ * loading tiles. Pointing `workerUrl` at a real file — mapbox's own documented CSP escape
+ * hatch — sidesteps the bug entirely, at any mapbox-gl version.
+ *
+ * Must be applied before the first `Map` is constructed.
+ *
+ * @param inputConfig - Configuration. Optional.
+ * @returns The applied configuration.
+ */
+declare function configureDbxMapboxWorker(inputConfig?: Maybe<DbxMapboxWorkerConfig>): Promise<DbxMapboxWorkerConfigurationResult>;
+
 /**
  * Configuration for provideDbxMapbox().
  */
 interface ProvideDbxMapboxConfig {
     readonly dbxMapboxConfig: DbxMapboxConfig;
     readonly ngxMapboxGLModuleConfig: Parameters<typeof provideMapboxGL>[0];
+    /**
+     * Configuration for the self-hosted mapbox-gl web worker.
+     *
+     * Enabled by default. See {@link configureDbxMapboxWorker} for why it is needed and
+     * which build asset the app must copy.
+     */
+    readonly worker?: Maybe<DbxMapboxWorkerConfig>;
 }
 /**
  * Creates EnvironmentProviders for providing DbxMapboxConfig and configuring the NgxMapboxGLModule.
  *
+ * Also registers an app initializer that points mapbox-gl at the self-hosted CSP web worker
+ * asset before any map is created.
+ *
  * @param config - Configuration.
  * @returns EnvironmentProviders.
  */
@@ -785,5 +867,5 @@ interface DbxMapboxEnvironmentOptions extends DbxMapboxConfig {
  */
 type DbxMapboxOptions = DbxMapboxEnvironmentOptions;
 
-export { DEFAULT_MAPBOX_CENTER, DEFAULT_MAPBOX_LAYOUT_DRAWER_WIDTH, DEFAULT_MAPBOX_MAP_STORE_TIMER_REFRESH_PERIOD, DEFAULT_MAPBOX_STYLE, DEFAULT_MAPBOX_ZOOM, DbxMapboxChangeService, DbxMapboxConfig, DbxMapboxInjectionComponent, DbxMapboxInjectionStore, DbxMapboxInjectionStoreInjectionBlockDirective, DbxMapboxInjectionStoreProviderBlock, DbxMapboxLayoutComponent, DbxMapboxLayoutDrawerComponent, DbxMapboxLayoutVirtualResizeSyncComponent, DbxMapboxMapDirective, DbxMapboxMapStore, DbxMapboxMapStoreInjectionBlockDirective, DbxMapboxMapStoreProviderBlock, DbxMapboxMarkerComponent, DbxMapboxMarkersComponent, DbxMapboxMenuComponent, DbxMapboxModule, DbxMapboxService, KNOWN_MAPBOX_STYLES, MAPBOX_MAX_ZOOM_LEVEL, MAPBOX_MIN_ZOOM_LEVEL, dbxMapboxColoredDotStyle, filterByMapboxViewportBound, mapboxViewportBoundFunction, mapboxZoomLevel, provideDbxMapbox, provideMapboxInjectionStoreIfParentIsUnavailable, provideMapboxStoreIfParentIsUnavailable, updateDbxMapboxMapInjectionStoreStateWithInjectionConfig, updateDbxMapboxMapInjectionStoreStateWithRemovedKey };
-export type { DbxMapboxClickEvent, DbxMapboxEnvironmentOptions, DbxMapboxInjectionConfig, DbxMapboxInjectionKey, DbxMapboxLayoutMode, DbxMapboxLayoutSide, DbxMapboxMapInjectionStoreState, DbxMapboxMarginCalculationSizing, DbxMapboxMarker, DbxMapboxMarkerDisplayConfig, DbxMapboxMarkerFactory, DbxMapboxMarkerPresentation, DbxMapboxMarkerSize, DbxMapboxOptions, DbxMapboxStoreBoundRefreshSettings, DbxMapboxStoreBoundRefreshType, DbxMapboxStoreState, FilterMapboxBoundConfig, FilterMapboxBoundReadItemValueFunction, KnownMapboxStyle, MapboxBearing, MapboxEaseTo, MapboxEaseToOptions, MapboxEaseToPositionOptions, MapboxEventData, MapboxFitBounds, MapboxFitBoundsOptions, MapboxFitPositions, MapboxFlyTo, MapboxFlyToOptions, MapboxFlyToPositionOptions, MapboxJumpTo, MapboxJumpToPositionOptions, MapboxMapLifecycleState, MapboxMapMoveState, MapboxMapRotateState, MapboxMapZoomState, MapboxPitch, MapboxResetNorth, MapboxResetNorthPitch, MapboxRotateTo, MapboxSetStyleOptions, MapboxSnapToNorth, MapboxStyleConfig, MapboxTileSize, MapboxViewportBoundFunction, MapboxViewportBoundFunctionConfig, MapboxViewportBoundFunctionInput, MapboxViewportBoundFunctionItem, MapboxViewportBoundFunctionItemValue, MapboxZoomLevel, MapboxZoomLevelRange, ProvideDbxMapboxConfig, StringMapboxListenerPair, TypedMapboxListenerPair };
+export { DEFAULT_DBX_MAPBOX_WORKER_URL, DEFAULT_MAPBOX_CENTER, DEFAULT_MAPBOX_LAYOUT_DRAWER_WIDTH, DEFAULT_MAPBOX_MAP_STORE_TIMER_REFRESH_PERIOD, DEFAULT_MAPBOX_STYLE, DEFAULT_MAPBOX_ZOOM, DbxMapboxChangeService, DbxMapboxConfig, DbxMapboxInjectionComponent, DbxMapboxInjectionStore, DbxMapboxInjectionStoreInjectionBlockDirective, DbxMapboxInjectionStoreProviderBlock, DbxMapboxLayoutComponent, DbxMapboxLayoutDrawerComponent, DbxMapboxLayoutVirtualResizeSyncComponent, DbxMapboxMapDirective, DbxMapboxMapStore, DbxMapboxMapStoreInjectionBlockDirective, DbxMapboxMapStoreProviderBlock, DbxMapboxMarkerComponent, DbxMapboxMarkersComponent, DbxMapboxMenuComponent, DbxMapboxModule, DbxMapboxService, KNOWN_MAPBOX_STYLES, MAPBOX_MAX_ZOOM_LEVEL, MAPBOX_MIN_ZOOM_LEVEL, configureDbxMapboxWorker, dbxMapboxColoredDotStyle, filterByMapboxViewportBound, isDbxMapboxWorkerAssetAvailable, mapboxViewportBoundFunction, mapboxZoomLevel, provideDbxMapbox, provideMapboxInjectionStoreIfParentIsUnavailable, provideMapboxStoreIfParentIsUnavailable, updateDbxMapboxMapInjectionStoreStateWithInjectionConfig, updateDbxMapboxMapInjectionStoreStateWithRemovedKey };
+export type { DbxMapboxClickEvent, DbxMapboxEnvironmentOptions, DbxMapboxInjectionConfig, DbxMapboxInjectionKey, DbxMapboxLayoutMode, DbxMapboxLayoutSide, DbxMapboxMapInjectionStoreState, DbxMapboxMarginCalculationSizing, DbxMapboxMarker, DbxMapboxMarkerDisplayConfig, DbxMapboxMarkerFactory, DbxMapboxMarkerPresentation, DbxMapboxMarkerSize, DbxMapboxOptions, DbxMapboxStoreBoundRefreshSettings, DbxMapboxStoreBoundRefreshType, DbxMapboxStoreState, DbxMapboxWorkerConfig, DbxMapboxWorkerConfigurationResult, FilterMapboxBoundConfig, FilterMapboxBoundReadItemValueFunction, KnownMapboxStyle, MapboxBearing, MapboxEaseTo, MapboxEaseToOptions, MapboxEaseToPositionOptions, MapboxEventData, MapboxFitBounds, MapboxFitBoundsOptions, MapboxFitPositions, MapboxFlyTo, MapboxFlyToOptions, MapboxFlyToPositionOptions, MapboxJumpTo, MapboxJumpToPositionOptions, MapboxMapLifecycleState, MapboxMapMoveState, MapboxMapRotateState, MapboxMapZoomState, MapboxPitch, MapboxResetNorth, MapboxResetNorthPitch, MapboxRotateTo, MapboxSetStyleOptions, MapboxSnapToNorth, MapboxStyleConfig, MapboxTileSize, MapboxViewportBoundFunction, MapboxViewportBoundFunctionConfig, MapboxViewportBoundFunctionInput, MapboxViewportBoundFunctionItem, MapboxViewportBoundFunctionItemValue, MapboxZoomLevel, MapboxZoomLevelRange, ProvideDbxMapboxConfig, StringMapboxListenerPair, TypedMapboxListenerPair };