@versatiles/style 5.5.2 → 5.6.0

package/README.MD

@@ -139,6 +139,10 @@ A local server will be available at <http://localhost:8080>. Use it to select a
 <!--- This chapter is generated automatically --->
 
 ```mermaid
+---
+config:
+  layout: elk
+---
 flowchart TB
 
 subgraph 0["src"]
@@ -239,14 +243,8 @@ Y-->7
 Y-->X
 Y-->E
 
-style 0 fill-opacity:0.2
-style 1 fill-opacity:0.2
-style 9 fill-opacity:0.2
-style B fill-opacity:0.2
-style D fill-opacity:0.2
-style G fill-opacity:0.2
-style I fill-opacity:0.2
-style T fill-opacity:0.2
+class 0,1,9,B,D,G,I,T subgraphs;
+classDef subgraphs fill-opacity:0.1, fill:#888, color:#888, stroke:#888;
 ```
 
 ## Licenses

package/dist/index.d.ts

@@ -21,6 +21,7 @@ declare class RGB extends Color {
     contrast(value: number): RGB;
     brightness(value: number): RGB;
     tint(value: number, tintColor: Color): RGB;
+    blend(value: number, blendColor: Color): RGB;
     lighten(ratio: number): RGB;
     darken(ratio: number): RGB;
     fade(value: number): RGB;
@@ -100,19 +101,115 @@ declare abstract class Color {
     lighten(value: number): RGB;
     darken(value: number): RGB;
     tint(value: number, tintColor: Color): RGB;
+    blend(value: number, blendColor: Color): RGB;
     setHue(value: number): HSV;
     abstract fade(value: number): Color;
 }
 
+/**
+ * Module for applying various color transformations such as hue rotation, saturation, contrast, brightness,
+ * tinting, and blending. These transformations are defined through the `RecolorOptions` interface.
+ */
+
+/**
+ * Configuration options for recoloring all map colors.
+ *
+ * The transformations (if specified) are done in the following order:
+ * 1. [Invert brightness](#invertbrightness)
+ * 2. [Rotate hue](#rotate)
+ * 3. [Saturate](#saturate)
+ * 4. [Gamma correction](#gamma)
+ * 5. [Contrast adjustment](#contrast)
+ * 6. [Brightness adjustment](#brightness)
+ * 7. [Tinting](#tint)
+ * 8. [Blending](#blend)
+ *
+ * Usage Examples
+ *
+ * ```typescript
+ * const style = VersaTilesStyle.colorful({
+ *    recolor: {
+ *       rotate: 180,
+ *       saturate: 0.5,
+ *       brightness: 0.2,
+ *    }
+ * };
+ * ```
+ *
+ * If you want do make you map simply brighter or darker, you can use the `blend` option:
+ * ```typescript
+ * const style = VersaTilesStyle.colorful({
+ *    recolor: {
+ *       blend: 0.5,
+ *       blendColor: '#000000', // to blend all colors with black
+ *       // or blendColor: '#FFFFFF', // to blend all colors with white
+ *    }
+ * };
+ * ```
+ *
+ */
 interface RecolorOptions {
+    /**
+     * If true, inverts all colors' brightness.
+     * See also {@link HSL.invertLuminosity}
+    */
     invertBrightness?: boolean;
+    /**
+     * Rotate the hue of all colors in degrees (0-360).
+     * See also {@link HSL.rotateHue}
+     */
     rotate?: number;
+    /**
+     * Adjust the saturation level. Positive values increase, negative values decrease saturation.
+     * |value|effect           |
+     * |----:|-----------------|
+     * |   -1|grayscale        |
+     * |    0|no effect        |
+     * |    1|double saturation|
+     *
+     * See also {@link HSL.saturate}
+     */
     saturate?: number;
+    /**
+     * Adjust the gamma (non-linear brightness adjustment).
+     * Defaults to 1.
+     * See also {@link RGB.gamma}
+     */
     gamma?: number;
+    /**
+     * Adjust the contrast level.
+     * Values > 1 increase contrast, values < 1 decrease it.
+     * Defaults to 1.
+     * See also {@link RGB.contrast}
+     */
     contrast?: number;
+    /**
+     * Adjust the brightness level.
+     * Positive values make it brighter, negative values make it darker.
+     * Defaults to 0.
+     *	See also {@link RGB.brightness}
+     */
     brightness?: number;
+    /**
+     * Intensity of the tinting effect (0 = none, 1 = full effect).
+     * See also {@link RGB.tint}
+     */
     tint?: number;
+    /**
+     * The tinting color in hex format (default: '#FF0000').
+     * See also {@link RGB.tint}
+     */
     tintColor?: string;
+    /**
+     * Intensity of the blending effect (0 = none, 1 = full effect).
+     * See also {@link RGB.blend}
+     */
+    blend?: number;
+    /**
+     * The blending color in hex format (default: '#000000').
+     *	See also {@link RGB.blend}
+     */
+    blendColor?: string;
 }
 
 /** Represents language suffixes used in map styles. */

package/dist/index.js

@@ -46,16 +46,30 @@ class Color {
     tint(value, tintColor) {
         return this.toRGB().tint(value, tintColor);
     }
+    blend(value, blendColor) {
+        return this.toRGB().blend(value, blendColor);
+    }
     setHue(value) {
         return this.toHSV().setHue(value);
     }
 }
 
-function clamp(num, min, max) {
-    return Math.min(Math.max(min, num), max);
+function clamp(value, min, max) {
+    if (value == null || isNaN(value))
+        return min;
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
 }
-function mod(num, max) {
-    return ((num % max) + max) % max;
+function mod(value, max) {
+    value = value % max;
+    if (value < 0)
+        value += max;
+    if (value == 0)
+        return 0;
+    return value;
 }
 function formatFloat(num, precision) {
     return num.toFixed(precision).replace(/0+$/, '').replace(/\.$/, '');
@@ -240,6 +254,11 @@ class RGB extends Color {
         const rgbNew = this.setHue(tintColor.toHSV().h).toRGB();
         return new RGB(this.r * (1 - value) + value * rgbNew.r, this.g * (1 - value) + value * rgbNew.g, this.b * (1 - value) + value * rgbNew.b, this.a);
     }
+    blend(value, blendColor) {
+        value = clamp(value ?? 0, 0, 1);
+        const rgbNew = blendColor.toRGB();
+        return new RGB(this.r * (1 - value) + value * rgbNew.r, this.g * (1 - value) + value * rgbNew.g, this.b * (1 - value) + value * rgbNew.b, this.a);
+    }
     lighten(ratio) {
         return new RGB(clamp(255 - (255 - this.r) * (1 - ratio), 0, 255), clamp(255 - (255 - this.g) * (1 - ratio), 0, 255), clamp(255 - (255 - this.b) * (1 - ratio), 0, 255), this.a);
     }
@@ -796,7 +815,6 @@ function getShortbreadLayers(option) {
                     });
                 });
                 // no links
-                const noDrivewayExpression = ['!=', 'service', 'driveway'];
                 ['track', 'pedestrian', 'service', 'living_street', 'residential', 'unclassified'].forEach(t => {
                     results.push({
                         id: prefix + 'street-' + t.replace(/_/g, '') + suffix,
@@ -805,7 +823,6 @@ function getShortbreadLayers(option) {
                         filter: ['all',
                             ['==', 'kind', t],
                             ...filter,
-                            ...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
                         ],
                     });
                 });
@@ -820,7 +837,6 @@ function getShortbreadLayers(option) {
                                 ['==', 'kind', t],
                                 ['==', 'bicycle', 'designated'],
                                 ...filter,
-                                ...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
                             ],
                         });
                     });
@@ -853,8 +869,9 @@ function getShortbreadLayers(option) {
             });
             // separate outline for trains
             [':outline', ''].forEach(suffix => {
-                // transport
-                ['rail', 'light_rail', 'subway', 'narrow_gauge', 'tram', 'funicular', 'monorail', 'bus_guideway', 'busway'].reverse().forEach((t) => {
+                // with service distinction
+                ['rail', 'light_rail', 'subway', 'narrow_gauge', 'tram'].reverse().forEach((t) => {
+                    // main rail
                     results.push({
                         id: prefix + 'transport-' + t.replace(/_/g, '') + suffix,
                         type: 'line',
@@ -865,6 +882,29 @@ function getShortbreadLayers(option) {
                             ...filter,
                         ],
                     });
+                    // service rail (crossover, siding, spur, yard)
+                    results.push({
+                        id: prefix + 'transport-' + t.replace(/_/g, '') + '-service' + suffix,
+                        type: 'line',
+                        'source-layer': 'streets',
+                        filter: ['all',
+                            ['in', 'kind', t],
+                            ['has', 'service'],
+                            ...filter,
+                        ],
+                    });
+                });
+                // other transport
+                ['funicular', 'monorail', 'bus_guideway', 'busway'].reverse().forEach((t) => {
+                    results.push({
+                        id: prefix + 'transport-' + t.replace(/_/g, '') + suffix,
+                        type: 'line',
+                        'source-layer': 'streets',
+                        filter: ['all',
+                            ['in', 'kind', t],
+                            ...filter,
+                        ],
+                    });
                 });
                 if (c === 'street') {
                     // aerialway, no bridges, above street evel
@@ -1828,6 +1868,13 @@ function decorate(layers, rules, recolor) {
     }
 }
 
+/**
+ * Module for applying various color transformations such as hue rotation, saturation, contrast, brightness,
+ * tinting, and blending. These transformations are defined through the `RecolorOptions` interface.
+ */
+/**
+ * Returns the default recolor settings.
+ */
 function getDefaultRecolorFlags() {
     return {
         invertBrightness: false,
@@ -1838,67 +1885,85 @@ function getDefaultRecolorFlags() {
         brightness: 0,
         tint: 0,
         tintColor: '#FF0000',
+        blend: 0,
+        blendColor: '#000000',
     };
 }
+/**
+ * Checks if the given options object contains any active recolor transformations.
+ * @param opt The recolor options to validate.
+ */
 function isValidRecolorOptions(opt) {
     if (!opt)
         return false;
-    if ((opt.invertBrightness != null) && opt.invertBrightness)
-        return true;
-    if ((opt.rotate != null) && (opt.rotate !== 0))
-        return true;
-    if ((opt.saturate != null) && (opt.saturate !== 0))
-        return true;
-    if ((opt.gamma != null) && (opt.gamma !== 1))
-        return true;
-    if ((opt.contrast != null) && (opt.contrast !== 1))
-        return true;
-    if ((opt.brightness != null) && (opt.brightness !== 0))
-        return true;
-    if ((opt.tint != null) && (opt.tint !== 0))
-        return true;
-    if ((opt.tintColor != null) && (opt.tintColor !== '#FF0000'))
-        return true;
-    return false;
+    return (opt.invertBrightness ||
+        (opt.rotate != null && opt.rotate !== 0) ||
+        (opt.saturate != null && opt.saturate !== 0) ||
+        (opt.gamma != null && opt.gamma !== 1) ||
+        (opt.contrast != null && opt.contrast !== 1) ||
+        (opt.brightness != null && opt.brightness !== 0) ||
+        (opt.tint != null && opt.tint !== 0) ||
+        (opt.tintColor != null && opt.tintColor !== '#FF0000') ||
+        (opt.blend != null && opt.blend !== 0) ||
+        (opt.blendColor != null && opt.blendColor !== '#000000'));
 }
+/**
+ * Caches recolored colors to optimize performance.
+ */
 class CachedRecolor {
     skip;
     opt;
     cache;
+    /**
+     * Creates a cached recolor instance.
+     * @param opt Optional recolor options.
+     */
     constructor(opt) {
         this.skip = !isValidRecolorOptions(opt);
         this.cache = new Map();
         this.opt = opt;
     }
+    /**
+     * Applies cached recoloring to a given color.
+     * @param color The color to recolor.
+     * @returns The recolored color, either from cache or newly computed.
+     */
     do(color) {
         if (this.skip)
             return color;
         const key = color.asHex();
-        const result = this.cache.get(key);
-        if (result)
-            return result;
-        color = recolor(color, this.opt);
-        this.cache.set(key, color);
-        return color;
+        if (this.cache.has(key))
+            return this.cache.get(key);
+        const recolored = recolor(color, this.opt);
+        this.cache.set(key, recolored);
+        return recolored;
     }
 }
+/**
+ * Applies the specified recoloring transformations to a single color.
+ * @param color The original color.
+ * @param opt Optional recolor options.
+ * @returns A new `Color` instance with applied transformations.
+ */
 function recolor(color, opt) {
     if (!isValidRecolorOptions(opt))
         return color;
-    if (opt.invertBrightness ?? false)
+    if (opt.invertBrightness)
         color = color.invertLuminosity();
-    if ((opt.rotate !== undefined) && (opt.rotate !== 0))
+    if (opt.rotate)
         color = color.rotateHue(opt.rotate);
-    if ((opt.saturate !== undefined) && (opt.saturate !== 0))
+    if (opt.saturate)
         color = color.saturate(opt.saturate);
-    if ((opt.gamma !== undefined) && (opt.gamma !== 1))
+    if (opt.gamma != null && opt.gamma != 1)
         color = color.gamma(opt.gamma);
-    if ((opt.contrast !== undefined) && (opt.contrast !== 1))
+    if (opt.contrast != null && opt.contrast != 1)
         color = color.contrast(opt.contrast);
-    if ((opt.brightness !== undefined) && (opt.brightness !== 0))
+    if (opt.brightness)
         color = color.brightness(opt.brightness);
-    if ((opt.tint !== undefined) && (opt.tintColor !== undefined) && (opt.tint !== 0))
+    if (opt.tint && opt.tintColor != null)
         color = color.tint(opt.tint, Color.parse(opt.tintColor));
+    if (opt.blend && opt.blendColor != null)
+        color = color.blend(opt.blend, Color.parse(opt.blendColor));
     return color;
 }
 
@@ -2463,15 +2528,26 @@ class Colorful extends StyleBuilder {
                 size: { 12: 1, 14: 2, 16: 5, 18: 24, 19: 60, 20: 120 },
                 opacity: { 12: 0, 13: 1 },
             },
-            // service and tracks
-            '{bridge-,tunnel-,}street-{service,track}:outline': {
+            // tracks
+            '{bridge-,tunnel-,}street-track:outline': {
                 size: { 14: 2, 16: 4, 18: 18, 19: 48, 20: 96 },
                 opacity: { 14: 0, 15: 1 },
             },
-            '{bridge-,tunnel-,}street-{service,track}': {
+            '{bridge-,tunnel-,}street-track': {
                 size: { 14: 1, 16: 3, 18: 16, 19: 44, 20: 88 },
                 opacity: { 14: 0, 15: 1 },
             },
+            // service
+            '{bridge-,tunnel-,}street-service:outline': {
+                size: { 14: 1, 16: 3, 18: 12, 19: 32, 20: 48 },
+                opacity: { 15: 0, 16: 1 },
+                color: colors.streetbg.lighten(0.3),
+            },
+            '{bridge-,tunnel-,}street-service': {
+                size: { 14: 1, 16: 2, 18: 10, 19: 28, 20: 40 },
+                opacity: { 15: 0, 16: 1 },
+                color: colors.street.darken(0.03),
+            },
             // ways
             '{bridge-,tunnel-,}way-*:outline': {
                 size: { 15: 0, 16: 5, 18: 7, 19: 12, 20: 22 },
@@ -2511,7 +2587,8 @@ class Colorful extends StyleBuilder {
             },
             // cycle streets overlay
             '{bridge-,tunnel-,}street-{tertiary,tertiary-link,unclassified,residential,livingstreet,pedestrian}-bicycle': {
-                lineCap: 'butt',
+                lineJoin: 'round',
+                lineCap: 'round',
                 color: colors.cycle,
             },
             // pedestrian
@@ -2527,11 +2604,25 @@ class Colorful extends StyleBuilder {
             // rail, lightrail
             '{tunnel-,bridge-,}transport-{rail,lightrail}:outline': {
                 color: colors.rail,
-                size: { 8: 1, 13: 1, 15: 3, 16: 4, 18: 8, 19: 11, 20: 14 },
+                minzoom: 8,
+                size: { 8: 1, 13: 1, 15: 1, 20: 14 },
             },
             '{tunnel-,bridge-,}transport-{rail,lightrail}': {
                 color: colors.rail.lighten(0.25),
-                size: { 8: 1, 13: 1, 15: 2, 16: 3, 18: 6, 19: 8, 20: 10 },
+                minzoom: 14,
+                size: { 14: 0, 15: 1, 20: 10 },
+                lineDasharray: [2, 2],
+            },
+            // rail-service, lightrail-service
+            '{tunnel-,bridge-,}transport-{rail,lightrail}-service:outline': {
+                color: colors.rail,
+                minzoom: 14,
+                size: { 14: 0, 15: 1, 16: 1, 20: 14 },
+            },
+            '{tunnel-,bridge-,}transport-{rail,lightrail}-service': {
+                color: colors.rail.lighten(0.25),
+                minzoom: 15,
+                size: { 15: 0, 16: 1, 20: 10 },
                 lineDasharray: [2, 2],
             },
             // subway
@@ -2707,7 +2798,7 @@ class Colorful extends StyleBuilder {
             'marking-oneway{-reverse,}': {
                 minzoom: 16,
                 image: 'basics:marking-arrow',
-                opacity: { 16: 0, 17: 0.7 },
+                opacity: { 16: 0, 17: 0.4, 20: 0.4 },
                 font: fonts.regular,
             },
             // TODO: bicycle and pedestrian