@versatiles/style 5.5.2 → 5.7.0

package/src/shortbread/layers.ts

@@ -193,7 +193,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 				});
 
 				// no links
-				const noDrivewayExpression: LegacyFilterSpecification = ['!=', 'service', 'driveway'];
 				['track', 'pedestrian', 'service', 'living_street', 'residential', 'unclassified'].forEach(t => {
 					results.push({
 						id: prefix + 'street-' + t.replace(/_/g, '') + suffix,
@@ -202,7 +201,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 						filter: ['all',
 							['==', 'kind', t],
 							...filter,
-							...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
 						],
 					});
 				});
@@ -217,7 +215,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 							['==', 'kind', t],
 							['==', 'bicycle', 'designated'],
 							...filter,
-							...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
 						],
 					});
 				});
@@ -254,8 +251,11 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 
 			// 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',
@@ -266,6 +266,31 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 							...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') {

package/src/style_builder/recolor.test.ts

@@ -15,6 +15,8 @@ describe('recolor', () => {
 				brightness: 0,
 				tint: 0,
 				tintColor: '#FF0000',
+				blend: 0,
+				blendColor: '#000000',
 			});
 		});
 	});
@@ -188,6 +190,50 @@ describe('recolor', () => {
 			expect(colors2string(colors)).toBe('7766DD00,0033EE55,1100FFAA,221188,665C99');
 		});
 	});
+
+	describe('blend', () => {
+		it('should not blend at all', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0, blendColor: '#F00' });
+			expect(colors2string(colors)).toBe('FFAA5500,00FFAA55,5500FFAA,AA5500,AA7755');
+		});
+
+		it('should blend a little bit red', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.5, blendColor: '#F00' });
+			expect(colors2string(colors)).toBe('FF552B00,80805555,AA0080AA,D52B00,D53C2B');
+		});
+
+		it('should blend a little bit yellow', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#FF0' });
+			expect(colors2string(colors)).toBe('FFBB4400,33FF8855,7733CCAA,BB7700,BB9244');
+		});
+
+		it('should blend a little bit green', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#0F0' });
+			expect(colors2string(colors)).toBe('CCBB4400,00FF8855,4433CCAA,887700,889244');
+		});
+
+		it('should blend a little bit blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#00F' });
+			expect(colors2string(colors)).toBe('CC887700,00CCBB55,4400FFAA,884433,885F77');
+		});
+
+		it('should blend strongly orange', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.8, blendColor: '#F80' });
+			expect(colors2string(colors)).toBe('FF8F1100,CCA02255,DD6D33AA,EE7E00,EE8511');
+		});
+
+		it('should blend a strongly blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.8, blendColor: '#00F' });
+			expect(colors2string(colors)).toBe('3322DD00,0033EE55,1100FFAA,2211CC,2218DD');
+		});
+	});
 });
 
 describe('recolorObject', () => {

package/src/style_builder/recolor.ts

@@ -1,31 +1,124 @@
+/**
+ * Module for applying various color transformations such as hue rotation, saturation, contrast, brightness,
+ * tinting, and blending. These transformations are defined through the `RecolorOptions` interface.
+ */
+
 import { Color } from '../color/index.js';
 
+/**
+ * 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
+ *   }
+ * };
+ * ```
+ * 
+ */
+
 export interface RecolorOptions {
-	// If true, inverts all colors.
+	/** 
+	 * If true, inverts all colors' brightness.
+	 * See also {@link HSL.invertLuminosity}
+	*/
 	invertBrightness?: boolean;
 
-	// Rotate the hue of all colors (in degrees).
+	/** 
+	 * Rotate the hue of all colors in degrees (0-360).
+	 * See also {@link HSL.rotateHue}
+	 */
 	rotate?: number;
 
-	// Adjusts the saturation level of all colors. Positive values increase saturation, negative values decrease it.
+	/** 
+	 * 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;
 
-	// Adjusts the gamma of all colors. Affects the brightness in a non-linear manner.
+	/**
+	 * Adjust the gamma (non-linear brightness adjustment).  
+	 * Defaults to 1.   
+	 * See also {@link RGB.gamma}
+	 */
 	gamma?: number;
 
-	// Adjusts the contrast of all colors. Higher values produce more contrast.
+	/**
+	 * Adjust the contrast level.  
+	 * Values > 1 increase contrast, values < 1 decrease it.  
+	 * Defaults to 1.  
+	 * See also {@link RGB.contrast}
+	 */
 	contrast?: number;
 
-	// Adjusts the brightness of all colors. Positive values make it brighter, negative values make it darker.
+	/**
+	 * Adjust the brightness level.  
+	 * Positive values make it brighter, negative values make it darker.  
+	 * Defaults to 0.  
+	 *	See also {@link RGB.brightness}
+	 */
 	brightness?: number;
 
-	// Specifies the intensity of the tinting effect. Ranges from 0 (no effect) to 1 (full effect).
+	/**
+	 * Intensity of the tinting effect (0 = none, 1 = full effect). 
+	 * See also {@link RGB.tint}
+	 */
 	tint?: number;
 
-	// Specifies the color used for tinting, in a string format (e.g., '#FF0000').
+	/**
+	 * 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;
 }
 
+/**
+ * Returns the default recolor settings.
+ */
 export function getDefaultRecolorFlags(): RecolorOptions {
 	return {
 		invertBrightness: false,
@@ -36,30 +129,49 @@ export function getDefaultRecolorFlags(): RecolorOptions {
 		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?: RecolorOptions): opt is RecolorOptions {
 	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')
+	);
 }
 
+/**
+ * Applies recoloring transformations to a record of colors.
+ * @param colors A record of color names to `Color` instances.
+ * @param opt Optional recolor options.
+ */
 export function recolorObject(colors: Record<string, Color>, opt?: RecolorOptions): void {
 	if (!isValidRecolorOptions(opt)) return;
 
-	for (const [k, c] of Object.entries(colors)) {
-		colors[k] = recolor(c, opt);
+	for (const [key, color] of Object.entries(colors)) {
+		colors[key] = recolor(color, opt);
 	}
 }
 
+/**
+ * Applies recoloring transformations to an array of colors.
+ * @param colors An array of `Color` instances.
+ * @param opt Optional recolor options.
+ */
 export function recolorArray(colors: Color[], opt?: RecolorOptions): void {
 	if (!isValidRecolorOptions(opt)) return;
 
@@ -68,43 +180,58 @@ export function recolorArray(colors: Color[], opt?: RecolorOptions): void {
 	}
 }
 
+/**
+ * Caches recolored colors to optimize performance.
+ */
 export class CachedRecolor {
 	private readonly skip: boolean;
-
 	private readonly opt?: RecolorOptions;
-
 	private readonly cache: Map<string, Color>;
 
+	/**
+	 * Creates a cached recolor instance.
+	 * @param opt Optional recolor options.
+	 */
 	public constructor(opt?: RecolorOptions) {
 		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.
+	 */
 	public do(color: Color): Color {
 		if (this.skip) return color;
 
 		const key = color.asHex();
+		if (this.cache.has(key)) return this.cache.get(key)!;
 
-		const result = this.cache.get(key);
-		if (result) return result;
-
-		color = recolor(color, this.opt);
-		this.cache.set(key, color);
-		return color;
+		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.
+ */
 export function recolor(color: Color, opt?: RecolorOptions): Color {
 	if (!isValidRecolorOptions(opt)) return color;
 
-	if (opt.invertBrightness ?? false) color = color.invertLuminosity();
-	if ((opt.rotate !== undefined) && (opt.rotate !== 0)) color = color.rotateHue(opt.rotate);
-	if ((opt.saturate !== undefined) && (opt.saturate !== 0)) color = color.saturate(opt.saturate);
-	if ((opt.gamma !== undefined) && (opt.gamma !== 1)) color = color.gamma(opt.gamma);
-	if ((opt.contrast !== undefined) && (opt.contrast !== 1)) color = color.contrast(opt.contrast);
-	if ((opt.brightness !== undefined) && (opt.brightness !== 0)) color = color.brightness(opt.brightness);
-	if ((opt.tint !== undefined) && (opt.tintColor !== undefined) && (opt.tint !== 0)) color = color.tint(opt.tint, Color.parse(opt.tintColor));
+	if (opt.invertBrightness) color = color.invertLuminosity();
+	if (opt.rotate) color = color.rotateHue(opt.rotate);
+	if (opt.saturate) color = color.saturate(opt.saturate);
+	if (opt.gamma != null && opt.gamma != 1) color = color.gamma(opt.gamma);
+	if (opt.contrast != null && opt.contrast != 1) color = color.contrast(opt.contrast);
+	if (opt.brightness) color = color.brightness(opt.brightness);
+	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;
 }

package/src/style_builder/style_builder.test.ts

@@ -80,6 +80,8 @@ describe('StyleBuilder', () => {
 				saturate: 0,
 				tint: 0,
 				tintColor: '#FF0000',
+				blend: 0,
+				blendColor: '#000000',
 			},
 			sprite: '',
 			tiles: [],

package/src/style_builder/style_builder.ts

@@ -4,7 +4,7 @@ import { decorate } from './decorator.js';
 import { CachedRecolor, getDefaultRecolorFlags } from './recolor.js';
 import { basename, deepClone, resolveUrl } from '../lib/utils.js';
 import type { MaplibreLayer, MaplibreLayerDefinition, StyleSpecification } from '../types/maplibre.js';
-import type { StyleBuilderColors, StyleBuilderColorsEnsured, StyleBuilderFonts, StyleBuilderOptions } from './types.js';
+import { styleBuilderColorKeys, type StyleBuilderColors, type StyleBuilderFonts, type StyleBuilderOptions } from './types.js';
 import type { StyleRules, StyleRulesOptions } from './types.js';
 import { SpriteSpecification } from '@maplibre/maplibre-gl-style-spec';
 
@@ -37,7 +37,7 @@ export abstract class StyleBuilder {
 
 		const colors = this.getColors(this.defaultColors);
 		if (options.colors) {
-			let key: keyof StyleBuilderColorsEnsured;
+			let key: keyof StyleBuilderColors;
 			for (key in options.colors) {
 				const value = options.colors[key];
 				if (value != null) colors[key] = Color.parse(value);
@@ -104,9 +104,9 @@ export abstract class StyleBuilder {
 		return style;
 	}
 
-	public getColors(colors: StyleBuilderColors): StyleBuilderColorsEnsured {
+	public getColors(colors: StyleBuilderColors): StyleBuilderColors<Color> {
 		const entriesString = Object.entries(colors) as [keyof StyleBuilderColors, string | Color][];
-		const result = Object.fromEntries(entriesString.map(([key, value]) => [key, Color.parse(value)])) as StyleBuilderColorsEnsured;
+		const result = Object.fromEntries(entriesString.map(([key, value]) => [key, Color.parse(value)])) as StyleBuilderColors<Color>;
 		return result;
 	}
 
@@ -114,9 +114,9 @@ export abstract class StyleBuilder {
 		return {
 			baseUrl: '',
 			bounds: [
-				-180, 
-				-85.0511287798066, 
-				180, 
+				-180,
+				-85.0511287798066,
+				180,
 				85.0511287798066
 			],
 			glyphs: '',
@@ -132,8 +132,7 @@ export abstract class StyleBuilder {
 
 	protected transformDefaultColors(callback: (color: Color) => Color): void {
 		const colors = this.getColors(this.defaultColors);
-		let key: keyof StyleBuilderColorsEnsured;
-		for (key in colors) {
+		for (const key of styleBuilderColorKeys) {
 			this.defaultColors[key] = callback(colors[key]);
 		}
 	}

package/src/style_builder/types.ts

@@ -5,113 +5,78 @@ import { SpriteSpecification } from '@maplibre/maplibre-gl-style-spec';
 /** Represents language suffixes used in map styles. */
 export type Language = 'de' | 'en' | null;
 
-/** Options for configuring a style builder. */
+/**
+ * Options for configuring the style builder.
+ */
 export interface StyleBuilderOptions {
 	/**
 	 * The base URL for loading external resources like tiles, sprites, and fonts.
-	 * Default: document.location.origin (in the browser), or 'https://tiles.versatiles.org'
+	 * @default document.location.origin (in the browser), or 'https://tiles.versatiles.org'
 	 */
 	baseUrl?: string;
 
-  /**
-   * The bounding box for the map, formatted as [sw.lng, sw.lat, ne.lng, ne.lat].
-   * Default: [-180, -85.0511287798066, 180, 85.0511287798066]
-   */
-  bounds?: [number, number, number, number];
+	/**
+	 * The bounding box for the map, formatted as [sw.lng, sw.lat, ne.lng, ne.lat].
+	 * @default [-180, -85.0511287798066, 180, 85.0511287798066]
+	 */
+	bounds?: [number, number, number, number];
 
 	/**
 	 * The URL template for loading font glyphs, formatted with '{fontstack}' and '{range}' placeholders.
-	 * Default: '/assets/glyphs/{fontstack}/{range}.pbf'
+	 * @default '/assets/glyphs/{fontstack}/{range}.pbf'
 	 */
 	glyphs?: string;
 
 	/**
 	 * The URL for loading sprite images and metadata.
-	 * Default: [{ id: 'basics', url: '/assets/sprites/basics/sprites' }]
+	 * @default [{ id: 'basics', url: '/assets/sprites/basics/sprites' }]
 	 */
 	sprite?: SpriteSpecification;
 
 	/**
 	 * An array of URL templates for loading map tiles, using '{z}', '{x}', and '{y}' placeholders.
-	 * Default: ['/tiles/osm/{z}/{x}/{y}']
+	 * @default ['/tiles/osm/{z}/{x}/{y}']
 	 */
 	tiles?: string[];
 
 	/**
 	 * If set to true, hides all map labels.
-	 * Default: false
+	 * @default false
 	 */
 	hideLabels?: boolean;
 
 	/**
 	 * Set the language ('en', 'de') of all map labels.
 	 * A null value means that the language of the country in which the label is drawn will be used.
-	 * Default: null
+	 * See also: {@link Language}
+	 * @default null
 	 */
 	language?: Language;
 
 	/**
 	 * An object specifying overrides for default color values, keyed by the color names.
+	 * See also: {@link StyleBuilderColors}
 	 */
 	colors?: Partial<StyleBuilderColors>;
 
 	/**
 	 * An object specifying overrides for default font names, keyed by the font names.
+	 * See also: {@link StyleBuilderFonts}
 	 */
 	fonts?: Partial<StyleBuilderFonts>;
 
 	/**
 	 * Options for color adjustments and transformations applied to the entire style.
+	 * See also: {@link RecolorOptions}
 	 */
 	recolor?: RecolorOptions;
 }
 
-/** Records string values for color properties in a style builder. */
-export interface StyleBuilderColors {
-	agriculture: Color | string;
-	boundary: Color | string;
-	building: Color | string;
-	buildingbg: Color | string;
-	burial: Color | string;
-	commercial: Color | string;
-	construction: Color | string;
-	cycle: Color | string;
-	danger: Color | string;
-	disputed: Color | string;
-	education: Color | string;
-	foot: Color | string;
-	glacier: Color | string;
-	grass: Color | string;
-	hospital: Color | string;
-	industrial: Color | string;
-	label: Color | string;
-	labelHalo: Color | string;
-	land: Color | string;
-	leisure: Color | string;
-	motorway: Color | string;
-	motorwaybg: Color | string;
-	park: Color | string;
-	parking: Color | string;
-	poi: Color | string;
-	prison: Color | string;
-	rail: Color | string;
-	residential: Color | string;
-	rock: Color | string;
-	sand: Color | string;
-	shield: Color | string;
-	street: Color | string;
-	streetbg: Color | string;
-	subway: Color | string;
-	symbol: Color | string;
-	trunk: Color | string;
-	trunkbg: Color | string;
-	waste: Color | string;
-	water: Color | string;
-	wetland: Color | string;
-	wood: Color | string;
-};
+export type StyleBuilderColorKey = 'agriculture' | 'boundary' | 'building' | 'buildingbg' | 'burial' | 'commercial' | 'construction' | 'cycle' | 'danger' | 'disputed' | 'education' | 'foot' | 'glacier' | 'grass' | 'hospital' | 'industrial' | 'label' | 'labelHalo' | 'land' | 'leisure' | 'motorway' | 'motorwaybg' | 'park' | 'parking' | 'poi' | 'prison' | 'rail' | 'residential' | 'rock' | 'sand' | 'shield' | 'street' | 'streetbg' | 'subway' | 'symbol' | 'trunk' | 'trunkbg' | 'waste' | 'water' | 'wetland' | 'wood';
+export const styleBuilderColorKeys: StyleBuilderColorKey[] = ['agriculture', 'boundary', 'building', 'buildingbg', 'burial', 'commercial', 'construction', 'cycle', 'danger', 'disputed', 'education', 'foot', 'glacier', 'grass', 'hospital', 'industrial', 'label', 'labelHalo', 'land', 'leisure', 'motorway', 'motorwaybg', 'park', 'parking', 'poi', 'prison', 'rail', 'residential', 'rock', 'sand', 'shield', 'street', 'streetbg', 'subway', 'symbol', 'trunk', 'trunkbg', 'waste', 'water', 'wetland', 'wood'] as const;
 
-export type StyleBuilderColorsEnsured = Record<keyof StyleBuilderColors, Color>;
+/** Records string values for color properties in a style builder. */
+export type StyleBuilderColors<T = Color | string> = Record<StyleBuilderColorKey, T>;
 
 /** Records string values for font properties in a style builder. */
 export type StyleBuilderFonts = {
@@ -124,7 +89,7 @@ export interface StyleRulesOptions {
 	/**
 	 * The set of colors used in the style builder.
 	 */
-	colors: StyleBuilderColorsEnsured;
+	colors: StyleBuilderColors<Color>;
 
 	/**
 	 * The set of fonts used in the style builder.