@tomtom-org/maps-sdk-plugin-map-effects 0.0.2

package/THIRD_PARTY.txt

@@ -0,0 +1,142 @@
+THIRD-PARTY SOFTWARE NOTICES FOR @tomtom-org/maps-sdk-plugin-map-effects
+
+This file lists the third-party components used by this package, together with
+their licenses. It is generated from the build output — do not edit it by hand.
+
+Components marked "Bundled: false (peer dependency)" are not shipped inside it:
+your package manager installs them alongside it and your application bundles them.
+The licenses below apply to those copies, and each such component may in turn install
+its own dependencies under their own licenses.
+
+The software itself is licensed under the terms in LICENSE.txt, which is not affected
+by the licenses reproduced here.
+
+--------------------------------------------------------------------------------
+
+Name: maplibre-gl
+Version: 6.9.0
+License: BSD-3-Clause
+Bundled: false (peer dependency)
+Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library
+Repository: https://github.com/maplibre/maplibre-gl-js
+Homepage: https://maplibre.org/
+License Text:
+===
+
+Copyright (c) 2023, MapLibre contributors
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of MapLibre GL JS nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+-------------------------------------------------------------------------------
+
+Contains code from mapbox-gl-js v1.13 and earlier
+
+Version v1.13 of mapbox-gl-js and earlier are licensed under a BSD-3-Clause license
+
+Copyright (c) 2020, Mapbox
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of Mapbox GL JS nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+-------------------------------------------------------------------------------
+
+Contains code from glfx.js
+
+Copyright (C) 2011 by Evan Wallace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Contains a portion of d3-color https://github.com/d3/d3-color
+
+Copyright 2010-2016 Mike Bostock
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author nor the names of contributors may be used to
+  endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

package/dist/THIRD_PARTY.txt

@@ -0,0 +1,131 @@
+The following third-party components are declared as peer dependencies. Their code is
+NOT bundled into this package: your package manager installs them alongside it and
+your application bundles them. The licenses below apply to those copies, and each of
+these components may in turn install its own dependencies under their own licenses.
+
+Name: maplibre-gl
+Version: 6.9.0
+License: BSD-3-Clause
+Bundled: false (peer dependency)
+Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library
+Repository: https://github.com/maplibre/maplibre-gl-js
+Homepage: https://maplibre.org/
+License Text:
+===
+
+Copyright (c) 2023, MapLibre contributors
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of MapLibre GL JS nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+-------------------------------------------------------------------------------
+
+Contains code from mapbox-gl-js v1.13 and earlier
+
+Version v1.13 of mapbox-gl-js and earlier are licensed under a BSD-3-Clause license
+
+Copyright (c) 2020, Mapbox
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of Mapbox GL JS nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+-------------------------------------------------------------------------------
+
+Contains code from glfx.js
+
+Copyright (C) 2011 by Evan Wallace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Contains a portion of d3-color https://github.com/d3/d3-color
+
+Copyright 2010-2016 Mike Bostock
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author nor the names of contributors may be used to
+  endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+import { KnobDescriptor, KnobRange, TomTomMap } from "@tomtom-org/maps-sdk/map";
+//#region src/effectsCatalogue.d.ts
+/**
+ * The range of a numeric effect knob. Every one ships a slider `step`; the shared {@link KnobRange}
+ * leaves it optional.
+ *
+ * @group Map Effects
+ */
+type EffectKnobRange = KnobRange & {
+  step: number;
+};
+/**
+ * The effects catalogue. Every effect is off at its default; each is named by the product problem it
+ * solves. Ordering is the compositing order: bloom → grade → fog → edge blur → tint → vignette.
+ * @ignore
+ */
+declare const effectKnobDefinitions: {
+  readonly 'bloom.intensity': {
+    readonly kind: "number";
+    readonly description: "How strongly bright features (lit roads, traffic tubes, route lines) glow. 0 = off.";
+    readonly default: 0;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Emphasis on dark and driving styles.";
+  };
+  readonly 'bloom.radius': {
+    readonly kind: "number";
+    readonly description: "How far the glow spreads, in CSS pixels.";
+    readonly default: 12;
+    readonly range: {
+      readonly min: 2;
+      readonly max: 40;
+      readonly step: 1;
+    };
+    readonly useCase: "Emphasis on dark and driving styles.";
+  };
+  readonly 'bloom.threshold': {
+    readonly kind: "number";
+    readonly description: "Brightness below which nothing glows. Raise it so only the brightest features light up.";
+    readonly default: 0.55;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Emphasis on dark and driving styles.";
+  };
+  readonly 'grade.brightness': {
+    readonly kind: "number";
+    readonly description: "Brightness of the whole base map (1 = unchanged).";
+    readonly default: 1;
+    readonly range: {
+      readonly min: 0.5;
+      readonly max: 1.5;
+      readonly step: 0.05;
+    };
+    readonly useCase: "Muting the base map under a data overlay.";
+  };
+  readonly 'grade.contrast': {
+    readonly kind: "number";
+    readonly description: "Contrast of the whole base map (1 = unchanged).";
+    readonly default: 1;
+    readonly range: {
+      readonly min: 0.5;
+      readonly max: 1.5;
+      readonly step: 0.05;
+    };
+    readonly useCase: "Muting the base map under a data overlay.";
+  };
+  readonly 'grade.saturation': {
+    readonly kind: "number";
+    readonly description: "Colour saturation of the whole base map (1 = unchanged, 0 = greyscale).";
+    readonly default: 1;
+    readonly range: {
+      readonly min: 0;
+      readonly max: 1.5;
+      readonly step: 0.05;
+    };
+    readonly useCase: "Muting the base map under a data overlay.";
+  };
+  readonly 'fog.intensity': {
+    readonly kind: "number";
+    readonly description: "Haze over the edges of the view: blur, plus a wash towards the colour of the air — pale on a light map, dark on a dark one. Reads as distance. 0 = off.";
+    readonly default: 0;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Depth cue: the far context recedes as if seen through air.";
+  };
+  readonly 'fog.reach': {
+    readonly kind: "number";
+    readonly description: "How far the fog reaches in from the edges (1 = to the centre).";
+    readonly default: 0.4;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Depth cue: the far context recedes as if seen through air.";
+  };
+  readonly 'edgeBlur.intensity': {
+    readonly kind: "number";
+    readonly description: "Blur over the edges of the view, in CSS pixels, leaving their colour untouched. Reads as a lens, not as distance — `fog` is the effect that also washes the rim out. 0 = off.";
+    readonly default: 0;
+    readonly range: {
+      readonly min: 0;
+      readonly max: 30;
+      readonly step: 1;
+    };
+    readonly useCase: "Focus: the centre stays sharp and the edges lose their detail.";
+  };
+  readonly 'edgeBlur.reach': {
+    readonly kind: "number";
+    readonly description: "How far the edge blur reaches in from the edges (1 = to the centre).";
+    readonly default: 0.5;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Focus: the centre stays sharp and the edges lose their detail.";
+  };
+  readonly 'tint.color': {
+    readonly kind: "color";
+    readonly description: "A flat colour laid over the whole map.";
+    readonly default: "#1f2937";
+    readonly useCase: "Muting the base map under a data overlay; matching a brand.";
+  };
+  readonly 'tint.opacity': {
+    readonly kind: "number";
+    readonly description: "Opacity of the tint. 0 = off.";
+    readonly default: 0;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Muting the base map under a data overlay; matching a brand.";
+  };
+  readonly 'vignette.intensity': {
+    readonly kind: "number";
+    readonly description: "Darkening (negative) or lightening (positive) towards the edges. 0 = off.";
+    readonly default: 0;
+    readonly range: {
+      readonly min: -1;
+      readonly max: 1;
+      readonly step: 0.05;
+    };
+    readonly useCase: "Focus on the centre of the view.";
+  };
+  readonly 'vignette.reach': {
+    readonly kind: "number";
+    readonly description: "How far the vignette reaches in from the edges (1 = to the centre).";
+    readonly default: 0.45;
+    readonly range: EffectKnobRange;
+    readonly useCase: "Focus on the centre of the view.";
+  };
+};
+/**
+ * The id of an effect knob, as accepted by {@link MapEffects.set}.
+ *
+ * @group Map Effects
+ */
+type EffectKnobId = keyof typeof effectKnobDefinitions;
+/**
+ * Every effect knob id, in compositing order.
+ *
+ * @group Map Effects
+ */
+export declare const effectKnobIds: EffectKnobId[];
+/**
+ * The value type an effect knob takes.
+ *
+ * @group Map Effects
+ */
+type EffectKnobValueOf<ID extends EffectKnobId> = (typeof effectKnobDefinitions)[ID]['kind'] extends 'color' ? string : number;
+//#endregion
+//#region src/MapEffects.d.ts
+/**
+ * The effect knob values an app sets — only the overridden ones, serializable like the SDK's
+ * styling settings.
+ *
+ * @group Map Effects
+ */
+type MapEffectsSettings = { [ID in EffectKnobId]?: EffectKnobValueOf<ID>; };
+/**
+ * One entry of the effects catalogue: the SDK's shared {@link KnobDescriptor}, narrowed the way
+ * `StylingKnobDescriptor` narrows it, plus the use case the effect serves.
+ *
+ * @group Map Effects
+ */
+type MapEffectsKnobDescriptor = KnobDescriptor<number | string> & {
+  /** The knob's id, as accepted by {@link MapEffects.set}. */
+  id: EffectKnobId;
+  /** The range of valid values, for every knob but `tint.color`. */
+  range?: EffectKnobRange;
+  /** Always `true`: an effect reads the rendered pixels, so it has something to work on anywhere. */
+  available: boolean;
+  /** Always `any-style`, for the same reason. */
+  appliesTo: string;
+  /** The practical problem the effect solves. */
+  useCase: string;
+};
+/**
+ * The effects catalogue, in the same shape as `StylingModule.describe()` so one control panel or
+ * agent tool can drive both.
+ *
+ * @group Map Effects
+ */
+type MapEffectsCatalogue = {
+  knobs: MapEffectsKnobDescriptor[];
+};
+/**
+ * Options for {@link MapEffects.capture}.
+ *
+ * @group Map Effects
+ */
+type CaptureOptions = {
+  /**
+   * Device pixels per CSS pixel to render at. Defaults to the map's current ratio; `2` or `3` gives
+   * a print-grade capture of the same view. MapLibre clamps to its `maxCanvasSize`, so measure the
+   * ratio you got from the returned canvas rather than assuming.
+   */
+  pixelRatio?: number;
+};
+/**
+ * Practical post-processing for a {@link TomTomMap}: effects computed from the rendered map's own
+ * pixels, not from its style — so they work on every style, custom ones included, survive every
+ * style release, and cannot be reproduced by editing the style at all.
+ *
+ * @remarks
+ * Every effect is named by the problem it solves, and off by default:
+ * - **bloom** — emphasis on dark and driving styles: lit roads, traffic tubes and route lines glow;
+ * - **grade** (brightness, contrast, saturation) and **tint** — muting the base map so a data overlay
+ *   reads first;
+ * - **fog** — depth: the rim is blurred *and* washed towards the colour of the air, which follows the
+ *   map's light/dark theme;
+ * - **edge blur** — focus: the rim is blurred and keeps its colour, so it reads as a lens rather than
+ *   as distance;
+ * - **vignette** — focus too, by darkening or lightening the edges.
+ *
+ * Effects render live as layers over the map canvas (`backdrop-filter` overlays; bloom is a small
+ * canvas blended in `screen` mode) and are composited the same way into {@link capture}, so what is
+ * captured is what was on screen. Bloom and capture read the map canvas, which needs
+ * `mapLibre: { canvasContextAttributes: { preserveDrawingBuffer: true } }` when creating the map;
+ * the plugin warns once when it is missing.
+ *
+ * {@link describe} returns the knobs in the same shape as `StylingModule.describe()`, so a control
+ * panel or an agent tool built for the SDK's styling catalogue reads this one unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { MapEffects } from '@tomtom-org/maps-sdk-plugin-map-effects';
+ *
+ * const effects = new MapEffects(map);
+ * // The data-viz muting half: a dim, desaturated base under your own layers.
+ * effects.set({ 'grade.saturation': 0.4, 'grade.brightness': 0.85, 'tint.opacity': 0.15 });
+ * // Night-driving emphasis on a dark style:
+ * effects.set({ 'bloom.intensity': 0.5, 'bloom.threshold': 0.6 });
+ *
+ * const poster = await effects.capture({ pixelRatio: 3 });
+ * ```
+ *
+ * @group Map Effects
+ */
+export declare class MapEffects {
+  private readonly map;
+  private settings;
+  private readonly container;
+  private readonly overlays;
+  private readonly bloomCanvas;
+  private bloomFrame;
+  private warnedBuffer;
+  private readonly onRender;
+  /**
+   * Attaches the effects to a map. Nothing is visible until {@link set} turns an effect on.
+   *
+   * @param map - The map to render effects over.
+   * @param settings - Effect knob values to apply right away.
+   */
+  constructor(map: TomTomMap, settings?: MapEffectsSettings);
+  /**
+   * Sets one or more effect knobs. Values are validated against the catalogue before anything is
+   * touched; knobs not mentioned keep their values.
+   *
+   * @param settings - Knob id → value.
+   * @throws `RangeError` for a value outside its range or of the wrong kind; `Error` for an unknown id.
+   *
+   * @example
+   * ```typescript
+   * effects.set({ 'vignette.intensity': -0.4 });
+   * ```
+   */
+  set(settings: MapEffectsSettings): void;
+  /**
+   * The current value of a knob: the override, or the catalogue default.
+   */
+  get<ID extends EffectKnobId>(id: ID): EffectKnobValueOf<ID>;
+  /**
+   * Turns a knob (or every knob) back to its default — for most effects, off.
+   */
+  reset(id?: EffectKnobId): void;
+  /**
+   * The overridden knobs, as a plain serializable object.
+   */
+  getConfig(): MapEffectsSettings;
+  /**
+   * Replaces every knob with the given settings (an empty object turns everything off).
+   */
+  applyConfig(settings: MapEffectsSettings): void;
+  /**
+   * The effects catalogue: every knob with kind, range, default, current value and the practical
+   * use case it serves. Same descriptor shape as `StylingModule.describe()`.
+   */
+  describe(): MapEffectsCatalogue;
+  /**
+   * Renders the current view — map and effects — into a canvas, optionally at a higher pixel ratio
+   * for print. The map is re-rendered at that ratio (never resampled), read back once every tile is
+   * drawn, and restored to follow the device afterwards.
+   *
+   * @remarks
+   * Needs `preserveDrawingBuffer: true` on the map's canvas context; without it the map half of the
+   * capture is blank. Viewers cannot download from a sandboxed page, so hand the canvas to your own
+   * upload or `toBlob` flow.
+   */
+  capture(options?: CaptureOptions): Promise<HTMLCanvasElement>;
+  /**
+   * Detaches the effects from the map and removes their elements.
+   */
+  remove(): void;
+  private render;
+  private scheduleBloom;
+  private drawBloom;
+  private readBack;
+  private settled;
+  private warnIfBufferNotPreserved;
+  private assertKnob;
+  private validate;
+}
+//#endregion
+export type { CaptureOptions, EffectKnobId, EffectKnobRange, EffectKnobValueOf, MapEffectsCatalogue, MapEffectsKnobDescriptor, MapEffectsSettings };

package/dist/index.es.js

@@ -0,0 +1,2 @@
+import{knob as e}from"@tomtom-org/maps-sdk/map";var t={min:0,max:1,step:.05},n="Emphasis on dark and driving styles.",a="Muting the base map under a data overlay.",i="Depth cue: the far context recedes as if seen through air.",s="Focus: the centre stays sharp and the edges lose their detail.",r="Muting the base map under a data overlay; matching a brand.",o="Focus on the centre of the view.",l={"bloom.intensity":{kind:"number",description:"How strongly bright features (lit roads, traffic tubes, route lines) glow. 0 = off.",default:0,range:t,useCase:n},"bloom.radius":{kind:"number",description:"How far the glow spreads, in CSS pixels.",default:12,range:{min:2,max:40,step:1},useCase:n},"bloom.threshold":{kind:"number",description:"Brightness below which nothing glows. Raise it so only the brightest features light up.",default:.55,range:t,useCase:n},"grade.brightness":{kind:"number",description:"Brightness of the whole base map (1 = unchanged).",default:1,range:{min:.5,max:1.5,step:.05},useCase:a},"grade.contrast":{kind:"number",description:"Contrast of the whole base map (1 = unchanged).",default:1,range:{min:.5,max:1.5,step:.05},useCase:a},"grade.saturation":{kind:"number",description:"Colour saturation of the whole base map (1 = unchanged, 0 = greyscale).",default:1,range:{min:0,max:1.5,step:.05},useCase:a},"fog.intensity":{kind:"number",description:"Haze over the edges of the view: blur, plus a wash towards the colour of the air — pale on a light map, dark on a dark one. Reads as distance. 0 = off.",default:0,range:t,useCase:i},"fog.reach":{kind:"number",description:"How far the fog reaches in from the edges (1 = to the centre).",default:.4,range:t,useCase:i},"edgeBlur.intensity":{kind:"number",description:"Blur over the edges of the view, in CSS pixels, leaving their colour untouched. Reads as a lens, not as distance — `fog` is the effect that also washes the rim out. 0 = off.",default:0,range:{min:0,max:30,step:1},useCase:s},"edgeBlur.reach":{kind:"number",description:"How far the edge blur reaches in from the edges (1 = to the centre).",default:.5,range:t,useCase:s},"tint.color":{kind:"color",description:"A flat colour laid over the whole map.",default:"#1f2937",useCase:r},"tint.opacity":{kind:"number",description:"Opacity of the tint. 0 = off.",default:0,range:t,useCase:r},"vignette.intensity":{kind:"number",description:"Darkening (negative) or lightening (positive) towards the edges. 0 = off.",default:0,range:{min:-1,max:1,step:.05},useCase:o},"vignette.reach":{kind:"number",description:"How far the vignette reaches in from the edges (1 = to the centre).",default:.45,range:t,useCase:o}},h=Object.keys(l),d=e=>Math.min(Math.max(e,0),1),g=(e,t,n=1)=>{const a=.92*d(t),i=(1+a)/(1-a);return`brightness(${(1/(1+a)).toFixed(4)}) contrast(${i.toFixed(3)}) blur(${e*n}px) saturate(1.35)`},c=(e,t,n)=>[1===e?"":`brightness(${e})`,1===t?"":`contrast(${t})`,1===n?"":`saturate(${n})`].filter(Boolean).join(" "),m=(e,t,n)=>`radial-gradient(ellipse farthest-corner at center, ${e} ${Math.round(100*(1-d(n)))}%, ${t} 100%)`,u=(e,t)=>{const{inner:n,outer:a}=b(e);return m(n,a,t)},b=e=>{const t=e<0?"0, 0, 0":"255, 255, 255";return{inner:`rgba(${t}, 0)`,outer:`rgba(${t}, ${Math.min(Math.abs(e),1)})`}},f=e=>m("transparent","black",e),p={light:{rgb:"238, 240, 244",grade:"brightness(1.08) contrast(0.82) saturate(0.7)"},dark:{rgb:"16, 22, 33",grade:"brightness(0.92) contrast(0.82) saturate(0.7)"}},v="saturate(1.08)",w=e=>p[e].grade,y=e=>2+6*e,C=(e,t)=>`blur(${y(e)}px) ${w(t)}`,k=(e,t)=>{const{rgb:n}=p[t];return{inner:`rgba(${n}, 0)`,outer:`rgba(${n}, ${.65*e})`}},x=(e,t,n)=>{const{inner:a,outer:i}=k(e,n);return m(a,i,t)},B=(e,t,n,a)=>{const i=document.createElement("canvas");i.width=t,i.height=n;const s=i.getContext("2d");if(s)return s.filter=a,s.drawImage(e.canvas,0,0),s.filter="none",s},$=(e,t,n,a=1)=>{e.save(),e.globalCompositeOperation=n,e.globalAlpha=a,e.drawImage(t.canvas,0,0),e.restore()},M=(e,t,n,a,i,s)=>{const r=t/Math.SQRT2,o=n/Math.SQRT2,l=e.createRadialGradient(0,0,1-a,0,0,1);l.addColorStop(0,i),l.addColorStop(1,s),e.save(),e.translate(t/2,n/2),e.scale(r,o),e.fillStyle=l,e.fillRect(-t/2/r,-n/2/o,t/r,n/o),e.restore()},R=(e,t,n,a,i,s,r)=>{const o=B(e,t,n,`blur(${i*a}px) ${r}`.trim());o&&(o.globalCompositeOperation="destination-in",M(o,t,n,s,"rgba(0,0,0,0)","rgba(0,0,0,1)"),e.drawImage(o.canvas,0,0))},S=(e,t,n,a,i,s)=>{i["bloom.intensity"]>0&&((e,t,n,a,i)=>{const s=g(i["bloom.radius"],i["bloom.threshold"],a),r=B(e,t,n,s);r&&$(e,r,"screen",i["bloom.intensity"])})(e,t,n,a,i);const r=c(i["grade.brightness"],i["grade.contrast"],i["grade.saturation"]);if(r&&((e,t,n,a)=>{const i=B(e,t,n,a);i&&$(e,i,"copy")})(e,t,n,r),i["fog.intensity"]>0){const r=i["fog.intensity"],o=i["fog.reach"],{inner:l,outer:h}=k(r,s);R(e,t,n,a,y(r),o,w(s)),M(e,t,n,o,l,h)}if(i["edgeBlur.intensity"]>0&&R(e,t,n,a,i["edgeBlur.intensity"],i["edgeBlur.reach"],v),i["tint.opacity"]>0&&(e.save(),e.globalAlpha=i["tint.opacity"],e.fillStyle=i["tint.color"],e.fillRect(0,0,t,n),e.restore()),0!==i["vignette.intensity"]){const{inner:a,outer:s}=b(i["vignette.intensity"]);M(e,t,n,i["vignette.reach"],a,s)}},E=e=>Object.fromEntries(h.map(t=>[t,e[t]??l[t].default])),F=["bloom","grade","fog","edgeBlur","tint","vignette"],I=e=>({backdropFilter:e,webkitBackdropFilter:e}),L=e=>({maskImage:e,webkitMaskImage:e}),O=class{map;settings={};container;overlays;bloomCanvas;bloomFrame;warnedBuffer=!1;onRender=()=>this.scheduleBloom();constructor(e,t={}){this.map=e;const n=this.map.mapLibreMap.getContainer();this.container=document.createElement("div"),this.container.className="tomtom-map-effects",Object.assign(this.container.style,{position:"absolute",inset:"0",pointerEvents:"none",overflow:"hidden"}),n.querySelector(".maplibregl-canvas-container")?.insertAdjacentElement("afterend",this.container)??n.appendChild(this.container),this.bloomCanvas=document.createElement("canvas"),this.overlays=Object.fromEntries(F.map(e=>{const t="bloom"===e?this.bloomCanvas:document.createElement("div");return t.dataset.effect=e,Object.assign(t.style,{position:"absolute",inset:"0",width:"100%",height:"100%",pointerEvents:"none",display:"none"}),this.container.appendChild(t),[e,t]})),this.bloomCanvas.style.mixBlendMode="screen",this.map.mapLibreMap.on("render",this.onRender),this.set(t)}set(e){for(const[t,n]of Object.entries(e))this.validate(t,n);this.settings={...this.settings,...e},this.render()}get(e){return this.assertKnob(e),this.settings[e]??l[e].default}reset(e){if(void 0===e)this.settings={};else{this.assertKnob(e);const{[e]:t,...n}=this.settings;this.settings=n}this.render()}getConfig(){return{...this.settings}}applyConfig(e){this.settings={},this.set(e)}describe(){return{knobs:h.map(t=>{const n=l[t];return e(t,n.kind,n.description,n.default,this.settings[t],{..."range"in n&&{range:n.range},available:!0,appliesTo:"any-style",useCase:n.useCase})})}}async capture(e={}){this.warnIfBufferNotPreserved();const t=this.map.mapLibreMap,n=t,a=t.getPixelRatio(),i=e.pixelRatio??a,s=a!==(globalThis.devicePixelRatio||1),r=Math.abs(i-a)>.01;r&&(n.setPixelRatio(i),await this.settled());try{return await this.readBack()}finally{r&&n.setPixelRatio(s?a:null)}}remove(){this.map.mapLibreMap.off("render",this.onRender),void 0!==this.bloomFrame&&cancelAnimationFrame(this.bloomFrame),this.container.remove()}render(){const e=E(this.settings),t=(e,t,n={})=>{const a=this.overlays[e];a.style.display=t?"block":"none",Object.assign(a.style,n)},n=c(e["grade.brightness"],e["grade.contrast"],e["grade.saturation"]);t("grade",""!==n,I(n));const a=this.map.styleLightDarkTheme;var i;t("fog",e["fog.intensity"]>0,{...I(C(e["fog.intensity"],a)),...L(f(e["fog.reach"])),backgroundImage:x(e["fog.intensity"],e["fog.reach"],a)}),t("edgeBlur",e["edgeBlur.intensity"]>0,{...I((i=e["edgeBlur.intensity"],`blur(${i}px) ${v}`)),...L(f(e["edgeBlur.reach"]))}),t("tint",e["tint.opacity"]>0,{backgroundColor:e["tint.color"],opacity:String(e["tint.opacity"])}),t("vignette",0!==e["vignette.intensity"],{backgroundImage:u(e["vignette.intensity"],e["vignette.reach"])});const s=e["bloom.intensity"]>0;t("bloom",s,{opacity:String(e["bloom.intensity"])}),s&&(this.warnIfBufferNotPreserved(),this.scheduleBloom())}scheduleBloom(){this.get("bloom.intensity")<=0||void 0!==this.bloomFrame||(this.bloomFrame=requestAnimationFrame(()=>{this.bloomFrame=void 0,this.drawBloom()}))}drawBloom(){const e=this.map.mapLibreMap.getCanvas(),t=Math.max(1,Math.round(.5*e.width)),n=Math.max(1,Math.round(.5*e.height));this.bloomCanvas.width===t&&this.bloomCanvas.height===n||(this.bloomCanvas.width=t,this.bloomCanvas.height=n);const a=this.bloomCanvas.getContext("2d");a&&(a.filter=g(this.get("bloom.radius"),this.get("bloom.threshold"),.5),a.clearRect(0,0,t,n),a.drawImage(e,0,0,t,n))}readBack(){const e=this.map.mapLibreMap;return new Promise(t=>{e.once("render",()=>{const n=e.getCanvas(),a=document.createElement("canvas");a.width=n.width,a.height=n.height;const i=a.getContext("2d");if(i){i.drawImage(n,0,0);const e=n.width/Math.max(1,n.clientWidth);S(i,n.width,n.height,e,E(this.settings),this.map.styleLightDarkTheme)}t(a)}),e.triggerRepaint()})}settled(e=15e3){const t=this.map.mapLibreMap;return new Promise(n=>{const a=()=>{clearTimeout(i),t.off("idle",a),n()},i=setTimeout(a,e);t.once("idle",a)})}warnIfBufferNotPreserved(){if(this.warnedBuffer)return;const e=this.map.mapLibreMap.getCanvas(),t=(e.getContext("webgl2")??e.getContext("webgl"))?.getContextAttributes?.();t&&!t.preserveDrawingBuffer&&(this.warnedBuffer=!0,console.warn("[MapEffects] bloom and capture read the map canvas, which needs `mapLibre: { canvasContextAttributes: { preserveDrawingBuffer: true } }` on the map's options."))}assertKnob(e){if(!(e in l))throw new Error(`Unknown effect knob '${e}'. Call describe() for the catalogue of knob ids.`)}validate(e,t){this.assertKnob(e);const{kind:n,range:a}=l[e];if("color"!==n){if("number"!=typeof t||!Number.isFinite(t))throw new RangeError(`Knob '${e}' expects a number; got ${String(t)}.`);if(a&&(t<a.min||t>a.max))throw new RangeError(`Knob '${e}' expects a number between ${a.min} and ${a.max}; got ${t}.`)}else if("string"!=typeof t||!t)throw new RangeError(`Knob '${e}' expects a CSS colour; got ${String(t)}.`)}};export{O as MapEffects,h as effectKnobIds};
+//# sourceMappingURL=index.es.js.map