@versatiles/style 5.2.6 → 5.2.7

package/src/style_builder/decorator.ts

@@ -0,0 +1,135 @@
+
+import { Color } from '../color/index.js';
+import expandBraces from 'brace-expansion';
+import maplibreProperties from '../shortbread/properties.js';
+import { deepMerge } from '../lib/utils.js';
+import type { MaplibreLayer } from '../types/index.js';
+import type { StyleRule, StyleRuleValue, StyleRules } from './types.js';
+import type { CachedRecolor } from './recolor.js';
+
+
+
+export function decorate(layers: MaplibreLayer[], rules: StyleRules, recolor: CachedRecolor): MaplibreLayer[] {
+	const layerIds = layers.map(l => l.id);
+	const layerIdSet = new Set(layerIds);
+
+	// Initialize a new map to hold final styles for layers
+	const layerStyles = new Map<string, StyleRule>();
+
+	// Iterate through the generated layer style rules
+	Object.entries(rules).forEach(([idDef, layerStyle]) => {
+		if (layerStyle == null) return;
+
+		// Expand any braces in IDs and filter them through a RegExp if necessary
+		const ids = expandBraces(idDef).flatMap(id => {
+			if (!id.includes('*')) return id;
+			const regExpString = id.replace(/[^a-z_:-]/g, c => {
+				if (c === '*') return '[a-z_-]*';
+				throw new Error('unknown char to process. Do not know how to make a RegExp from: ' + JSON.stringify(c));
+			});
+			const regExp = new RegExp(`^${regExpString}$`, 'i');
+			return layerIds.filter(layerId => regExp.test(layerId));
+		});
+
+		ids.forEach(id => {
+			if (!layerIdSet.has(id)) return;
+			layerStyles.set(id, deepMerge(layerStyles.get(id) ?? {}, layerStyle));
+		});
+	});
+
+	// Deep clone the original layers and apply styles
+	return layers.flatMap(layer => {
+		// Get the id and style of the layer
+		const layerStyle = layerStyles.get(layer.id);
+
+		// Don't export layers that have no style
+		if (!layerStyle) return [];
+
+		processStyling(layer, layerStyle);
+
+		return [layer];
+	});
+
+	// Function to process each style attribute for the layer
+	function processStyling(layer: MaplibreLayer, styleRule: StyleRule): void {
+
+		for (const [ruleKeyCamelCase, ruleValue] of Object.entries(styleRule)) {
+			if (ruleValue == null) continue;
+
+			// CamelCase to not-camel-case
+			const ruleKey = ruleKeyCamelCase.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+
+			const propertyDefs = maplibreProperties.get(layer.type + '/' + ruleKey);
+			if (!propertyDefs) continue;
+
+			propertyDefs.forEach(propertyDef => {
+				const { key } = propertyDef;
+				let value: StyleRuleValue = ruleValue;
+
+				switch (propertyDef.valueType) {
+					case 'color': value = processExpression(value, processColor); break;
+					case 'fonts': value = processExpression(value, processFont); break;
+					case 'resolvedImage':
+					case 'formatted':
+					case 'array':
+					case 'boolean':
+					case 'enum':
+					case 'number': value = processExpression(value); break;
+					default: throw new Error(`unknown propertyDef.valueType "${propertyDef.valueType}" for key "${key}"`);
+				}
+
+				switch (propertyDef.parent) {
+					case 'layer':
+						// @ts-expect-error: too complex to handle
+						layer[key] = value;
+						break;
+					case 'layout':
+						if (!layer.layout) layer.layout = {};
+						// @ts-expect-error: too complex to handle
+						layer.layout[key] = value;
+						break;
+					case 'paint':
+						if (!layer.paint) layer.paint = {};
+						// @ts-expect-error: too complex to handle
+						layer.paint[key] = value;
+						break;
+					default:
+
+						throw new Error(`unknown parent "${propertyDef.parent}" for key "${key}"`);
+				}
+			});
+		}
+
+		function processColor(value: StyleRuleValue): string {
+			if (typeof value === 'string') value = Color.parse(value);
+			if (value instanceof Color) {
+				const color = recolor.do(value as Color);
+				return color.asString()
+			}
+			throw new Error(`unknown color type "${typeof value}"`);
+		}
+
+		function processFont(value: StyleRuleValue): string[] {
+			if (typeof value === 'string') return [value];
+			throw new Error(`unknown font type "${typeof value}"`);
+		}
+
+		function processExpression(value: StyleRuleValue, cbValue?: (value: StyleRuleValue) => StyleRuleValue): StyleRuleValue {
+			if (typeof value === 'object') {
+				if (value instanceof Color) return processColor(value);
+				if (!Array.isArray(value)) {
+					return processZoomStops(value as Record<string, StyleRuleValue>, cbValue);
+				}
+			}
+			return cbValue ? cbValue(value) : value;
+		}
+
+		function processZoomStops(obj: Record<string, StyleRuleValue>, cbValue?: (value: StyleRuleValue) => StyleRuleValue): { stops: StyleRuleValue[] } {
+			return {
+				stops: Object.entries(obj)
+					.map(([z, v]) => [parseInt(z, 10), cbValue ? cbValue(v) : v] as [number, StyleRuleValue])
+					.sort((a, b) => a[0] - b[0]),
+			};
+		}
+	}
+}

package/src/style_builder/recolor.test.ts

@@ -0,0 +1,306 @@
+import { Color } from '../color/index.js';
+import { CachedRecolor, getDefaultRecolorFlags, recolorArray, recolorObject } from './recolor.js';
+
+
+describe('recolor', () => {
+	describe('getDefaultRecolorFlags', () => {
+		it('should return the default color transformer flags', () => {
+			const defaultFlags = getDefaultRecolorFlags();
+			expect(defaultFlags).toEqual({
+				invertBrightness: false,
+				rotate: 0,
+				saturate: 0,
+				gamma: 1,
+				contrast: 1,
+				brightness: 0,
+				tint: 0,
+				tintColor: '#FF0000',
+			});
+		});
+	});
+
+	it('should not alter the colors if no flags are provided', () => {
+		const colors = getTestColors();
+		recolorArray(colors, {});
+		expect(colors).toEqual(getTestColors());
+	});
+
+	describe('invertBrightness', () => {
+		it('should invert brightness when invert flag is true', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { invertBrightness: true });
+			expect(colors2string(colors)).toBe('AA550000,00FFAA55,5500FFAA,FFAA55,AA7755');
+		});
+	});
+
+	describe('rotate', () => {
+		it('should rotate colors 120°', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { rotate: 120 });
+			expect(colors2string(colors)).toBe('55FFAA00,AA00FF55,FF5500AA,00AA55,55AA77');
+		});
+
+		it('should rotate colors 180°', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { rotate: 180 });
+			expect(colors2string(colors)).toBe('55AAFF00,FF005555,AAFF00AA,0055AA,5588AA');
+		});
+
+		it('should rotate colors 240°', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { rotate: 240 });
+			expect(colors2string(colors)).toBe('AA55FF00,FFAA0055,00FF55AA,5500AA,7755AA');
+		});
+	});
+
+	describe('saturation', () => {
+		it('should remove any saturation', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { saturate: -1.0 });
+			expect(colors2string(colors)).toBe('AAAAAA00,80808055,808080AA,555555,808080');
+		});
+
+		it('should decrease saturation', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { saturate: -0.5 });
+			expect(colors2string(colors)).toBe('D4AA7F00,40BF9555,6A40BFAA,7F552A,957B6A');
+		});
+
+		it('should increase saturation', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { saturate: 0.5 });
+			expect(colors2string(colors)).toBe('FFAA5500,00FFAA55,5500FFAA,AA5500,BF7340');
+		});
+
+		it('should maximize saturation', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { saturate: 1.0 });
+			expect(colors2string(colors)).toBe('FFAA5500,00FFAA55,5500FFAA,AA5500,D46F2B');
+		});
+	});
+
+	describe('gamma', () => {
+		it('should decrease gamma', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { gamma: 0.5 });
+			expect(colors2string(colors)).toBe('FFD09300,00FFD055,9300FFAA,D09300,D0AE93');
+		});
+
+		it('should increase gamma', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { gamma: 2 });
+			expect(colors2string(colors)).toBe('FF711C00,00FF7155,1C00FFAA,711C00,71381C');
+		});
+	});
+
+	describe('contrast', () => {
+		it('should remove any contrast', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { contrast: 0 });
+			expect(colors2string(colors)).toBe('80808000,80808055,808080AA,808080,808080');
+		});
+
+		it('should decrease contrast', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { contrast: 0.5 });
+			expect(colors2string(colors)).toBe('BF956A00,40BF9555,6A40BFAA,956A40,957B6A');
+		});
+
+		it('should increase contrast', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { contrast: 2 });
+			expect(colors2string(colors)).toBe('FFD52B00,00FFD555,2B00FFAA,D52B00,D56F2B');
+		});
+
+		it('should maximize contrast', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { contrast: Infinity });
+			expect(colors2string(colors)).toBe('FFFF0000,00FFFF55,0000FFAA,FF0000,FF0000');
+		});
+	})
+
+	describe('brightness', () => {
+		it('should remove any brightness', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { brightness: -1 });
+			expect(colors2string(colors)).toBe('00000000,00000055,000000AA,000000,000000');
+		});
+
+		it('should decrease brightness', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { brightness: -0.5 });
+			expect(colors2string(colors)).toBe('80552B00,00805555,2B0080AA,552B00,553C2B');
+		});
+
+		it('should increase brightness', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { brightness: 0.5 });
+			expect(colors2string(colors)).toBe('FFD5AA00,80FFD555,AA80FFAA,D5AA80,D5BBAA');
+		});
+
+		it('should maximize brightness', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { brightness: 1 });
+			expect(colors2string(colors)).toBe('FFFFFF00,FFFFFF55,FFFFFFAA,FFFFFF,FFFFFF');
+		});
+	});
+
+	describe('tint', () => {
+		it('should not tint at all', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0, tintColor: '#F00' });
+			expect(colors2string(colors)).toBe('FFAA5500,00FFAA55,5500FFAA,AA5500,AA7755');
+		});
+
+		it('should tint a little bit red', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.5, tintColor: '#F00' });
+			expect(colors2string(colors)).toBe('FF805500,80805555,AA0080AA,AA2B00,AA6655');
+		});
+
+		it('should tint a little bit yellow', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.2, tintColor: '#FF0' });
+			expect(colors2string(colors)).toBe('FFBB5500,33FF8855,7733CCAA,AA6600,AA8155');
+		});
+
+		it('should tint a little bit green', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.2, tintColor: '#0F0' });
+			expect(colors2string(colors)).toBe('DDBB5500,00FF8855,4433CCAA,886600,998155');
+		});
+
+		it('should tint a little bit blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.2, tintColor: '#00F' });
+			expect(colors2string(colors)).toBe('DD997700,00CCBB55,4400FFAA,884422,997066');
+		});
+
+		it('should tint strongly orange', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.8, tintColor: '#F80' });
+			expect(colors2string(colors)).toBe('FFAF5500,CCA02255,DD6D33AA,AA5A00,AA8055');
+		});
+
+		it('should tint a strongly blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { tint: 0.8, tintColor: '#00F' });
+			expect(colors2string(colors)).toBe('7766DD00,0033EE55,1100FFAA,221188,665C99');
+		});
+	});
+});
+
+describe('recolorObject', () => {
+	it('should recolor an object of colors', () => {
+		const colors = {
+			color1: Color.parse('#FA50'),
+			color2: Color.parse('#0FA5'),
+			color3: Color.parse('#50FA'),
+		};
+		recolorObject(colors, { rotate: 120 });
+		expect(colors.color1.asHex()).toBe('#55FFAA00');
+		expect(colors.color2.asHex()).toBe('#AA00FF55');
+		expect(colors.color3.asHex()).toBe('#FF5500AA');
+	});
+
+	it('should not alter colors if options are invalid', () => {
+		const colors = {
+			color1: Color.parse('#FA50'),
+			color2: Color.parse('#0FA5'),
+			color3: Color.parse('#50FA'),
+		};
+		const original = { ...colors };
+		recolorObject(colors, {});
+		expect(colors).toEqual(original);
+	});
+});
+
+describe('recolorArray', () => {
+	it('should recolor an array of colors with valid options', () => {
+		const colors = getTestColors();
+		recolorArray(colors, { rotate: 120 });
+		expect(colors.map((c) => c.asHex())).toEqual([
+			'#55FFAA00',
+			'#AA00FF55',
+			'#FF5500AA',
+			'#00AA55',
+			'#55AA77',
+		]);
+	});
+
+	it('should not alter the array if options are invalid', () => {
+		const colors = getTestColors();
+		const original = [...colors];
+		recolorArray(colors, {});
+		expect(colors).toEqual(original);
+	});
+
+	it('should handle multiple transformations on the same array', () => {
+		const colors = getTestColors();
+		recolorArray(colors, { saturate: 0.5 });
+		expect(colors.map((c) => c.asHex())).toEqual([
+			'#FFAA5500',
+			'#00FFAA55',
+			'#5500FFAA',
+			'#AA5500',
+			'#BF7340',
+		]);
+
+		recolorArray(colors, { brightness: 0.5 });
+		expect(colors.map((c) => c.asHex())).toEqual([
+			'#FFD5AA00',
+			'#80FFD555',
+			'#AA80FFAA',
+			'#D5AA80',
+			'#DFB99F',
+		]);
+	});
+});
+
+describe('CachedRecolor', () => {
+	it('should apply recolor transformations and cache the results', () => {
+		const cachedRecolor = new CachedRecolor({ rotate: 120 });
+		const color = Color.parse('#FA50');
+		const recolored = cachedRecolor.do(color);
+		expect(recolored.asHex()).toBe('#55FFAA00');
+
+		// Verify cached result
+		const cachedResult = cachedRecolor.do(color);
+		expect(cachedResult).toBe(recolored); // Cached object should be the same instance
+	});
+
+	it('should skip recoloring if options are invalid', () => {
+		const cachedRecolor = new CachedRecolor({});
+		const color = Color.parse('#FA50');
+		const recolored = cachedRecolor.do(color);
+		expect(recolored).toBe(color); // No changes applied
+	});
+
+	it('should handle multiple recoloring operations', () => {
+		const cachedRecolor = new CachedRecolor({ saturate: 0.5 });
+		const colors = getTestColors();
+
+		const recoloredColors = colors.map((color) => cachedRecolor.do(color));
+		expect(recoloredColors.map((c) => c.asHex())).toEqual([
+			'#FFAA5500',
+			'#00FFAA55',
+			'#5500FFAA',
+			'#AA5500',
+			'#BF7340',
+		]);
+	});
+});
+
+function getTestColors(): Color[] {
+	return [
+		Color.parse('#FA50'),
+		Color.parse('#0FA5'),
+		Color.parse('#50FA'),
+		Color.parse('#A50F'),
+		Color.parse('#A75F'),
+	];
+}
+
+function colors2string(colors: Color[]): string {
+	return colors.map(c => c.asHex().slice(1)).join(',');
+}

package/src/style_builder/recolor.ts

@@ -0,0 +1,110 @@
+import { Color } from '../color/index.js';
+
+export interface RecolorOptions {
+	// If true, inverts all colors.
+	invertBrightness?: boolean;
+
+	// Rotate the hue of all colors (in degrees).
+	rotate?: number;
+
+	// Adjusts the saturation level of all colors. Positive values increase saturation, negative values decrease it.
+	saturate?: number;
+
+	// Adjusts the gamma of all colors. Affects the brightness in a non-linear manner.
+	gamma?: number;
+
+	// Adjusts the contrast of all colors. Higher values produce more contrast.
+	contrast?: number;
+
+	// Adjusts the brightness of all colors. Positive values make it brighter, negative values make it darker.
+	brightness?: number;
+
+	// Specifies the intensity of the tinting effect. Ranges from 0 (no effect) to 1 (full effect).
+	tint?: number;
+
+	// Specifies the color used for tinting, in a string format (e.g., '#FF0000').
+	tintColor?: string;
+}
+
+export function getDefaultRecolorFlags(): RecolorOptions {
+	return {
+		invertBrightness: false,
+		rotate: 0,
+		saturate: 0,
+		gamma: 1,
+		contrast: 1,
+		brightness: 0,
+		tint: 0,
+		tintColor: '#FF0000',
+	};
+}
+
+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;
+}
+
+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);
+	}
+}
+
+export function recolorArray(colors: Color[], opt?: RecolorOptions): void {
+	if (!isValidRecolorOptions(opt)) return;
+
+	for (let i = 0; i < colors.length; i++) {
+		colors[i] = recolor(colors[i], opt);
+	}
+}
+
+export class CachedRecolor {
+	private readonly skip: boolean;
+
+	private readonly opt?: RecolorOptions;
+
+	private readonly cache: Map<string, Color>;
+
+	public constructor(opt?: RecolorOptions) {
+		this.skip = !isValidRecolorOptions(opt);
+		this.cache = new Map();
+		this.opt = opt;
+	}
+
+	public do(color: Color): 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;
+	}
+}
+
+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));
+
+	return color;
+}

package/src/style_builder/style_builder.test.ts

@@ -0,0 +1,103 @@
+
+import { Color } from '../color/index.js';
+import type { StyleRules, StyleRulesOptions } from './types.js';
+import { StyleBuilder } from './style_builder.js';
+import { VectorSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+import Colorful from '../styles/colorful.js';
+
+// Mock class for abstract class StyleBuilder
+class MockStyleBuilder extends Colorful {
+	public readonly name = 'mock';
+
+	public defaultFonts = { regular: 'Arial', bold: 'Courier' };
+
+	public invertColors(): void {
+		this.transformDefaultColors(color => color.invert());
+	}
+
+	protected getStyleRules(opt: StyleRulesOptions): StyleRules {
+		for (const color of Object.values(opt.colors)) if (!(color instanceof Color)) throw Error();
+		for (const font of Object.values(opt.fonts)) if (typeof font !== 'string') throw Error();
+
+		return {
+			'water-area': {
+				textColor: opt.colors.land,
+				textSize: 12,
+				textFont: opt.fonts.regular,
+			},
+		};
+	}
+}
+
+describe('StyleBuilder', () => {
+	let builder: MockStyleBuilder;
+
+	beforeEach(() => {
+		builder = new MockStyleBuilder();
+	});
+
+	it('should create an instance of StyleBuilder', () => {
+		expect(builder).toBeInstanceOf(StyleBuilder);
+	});
+
+	it('should build a MaplibreStyle object', () => {
+		const style = builder.build();
+		expect(style).toBeDefined();
+		expect(style).toHaveProperty('name');
+		expect(style).toHaveProperty('layers');
+		expect(style).toHaveProperty('glyphs');
+		expect(style).toHaveProperty('sprite');
+	});
+
+	it('should transform colors correctly', () => {
+		const initialColor = Color.parse(builder.defaultColors.land).asHex();
+		builder.invertColors();
+		const newColor = Color.parse(builder.defaultColors.land).asHex();
+		expect(newColor).not.toBe(initialColor);
+		expect(newColor).toBe(Color.parse(initialColor).invert().asHex());
+	});
+
+	it('should create default options', () => {
+		expect(builder.getDefaultOptions()).toStrictEqual({
+			baseUrl: '',
+			colors: expect.any(Object),
+			fonts: { regular: 'Arial', bold: 'Courier' },
+			glyphs: '',
+			hideLabels: false,
+			language: undefined,
+			recolor: {
+				brightness: 0,
+				contrast: 1,
+				gamma: 1,
+				invertBrightness: false,
+				rotate: 0,
+				saturate: 0,
+				tint: 0,
+				tintColor: '#FF0000',
+			},
+			sprite: '',
+			tiles: [],
+		});
+	});
+
+	describe('build method', () => {
+		it('should create a style object', () => {
+			const style = builder.build();
+			expect(style).toBeDefined();
+			expect(style).toHaveProperty('layers');
+			expect(style).toHaveProperty('name');
+			expect(style).toHaveProperty('glyphs');
+			expect(style).toHaveProperty('sprite');
+		});
+
+		it('should resolve urls correctly', () => {
+			const style = builder.build({ baseUrl: 'https://my.base.url/' });
+			expect(style.glyphs).toBe('https://my.base.url/assets/glyphs/{fontstack}/{range}.pbf');
+			expect(style.sprite).toStrictEqual([{ id: 'basics', url: 'https://my.base.url/assets/sprites/basics/sprites' }]);
+
+			const source = style.sources['versatiles-shortbread'] as VectorSourceSpecification;
+			expect(source).toHaveProperty('tiles');
+			expect(source.tiles).toStrictEqual(['https://my.base.url/tiles/osm/{z}/{x}/{y}']);
+		});
+	});
+});