@versatiles/style 5.6.0 → 5.8.0

package/dist/index.d.ts

@@ -1,108 +1,504 @@
 import { SpriteSpecification, StyleSpecification } from '@maplibre/maplibre-gl-style-spec';
+export { SpriteSpecification } from '@maplibre/maplibre-gl-style-spec';
 
+interface RandomColorOptions {
+    seed?: string;
+    hue?: number | string;
+    opacity?: number;
+    luminosity?: number | string;
+    saturation?: number | string;
+}
+
+/**
+ * Represents an RGB color with optional alpha transparency.
+ *
+ * @extends Color
+ */
 declare class RGB extends Color {
+    /**
+     * Red component (0-255).
+     */
     readonly r: number;
+    /**
+     * Green component (0-255).
+     */
     readonly g: number;
+    /**
+     * Blue component (0-255).
+     */
     readonly b: number;
+    /**
+     * Alpha component (0-1).
+     */
     readonly a: number;
+    /**
+     * Creates an instance of RGB.
+     *
+     * @param r - Red component (0-255).
+     * @param g - Green component (0-255).
+     * @param b - Blue component (0-255).
+     * @param a - Alpha component (0-1), defaults to 1.
+     */
     constructor(r: number, g: number, b: number, a?: number);
+    /**
+     * Creates a clone of the current RGB color.
+     *
+     * @returns A new RGB instance with the same color values.
+     */
     clone(): RGB;
+    /**
+     * Returns the RGB color as an array.
+     *
+     * @returns An array containing the red, green, blue, and alpha components.
+     */
     asArray(): [number, number, number, number];
+    /**
+     * Rounds the RGB color components to the nearest integer.
+     *
+     * @returns A new RGB instance with rounded color values.
+     */
     round(): RGB;
+    /**
+     * Returns the RGB color as a string.
+     *
+     * @returns A string representation of the RGB color in either `rgb` or `rgba` format.
+     */
     asString(): string;
+    /**
+     * Returns the RGB color as a hexadecimal string.
+     *
+     * @returns A string representation of the RGB color in hexadecimal format.
+     */
     asHex(): string;
+    /**
+     * Converts the RGB color to an HSL color.
+     *
+     * @returns An HSL instance representing the same color.
+     */
     asHSL(): HSL;
+    /**
+     * Converts the RGB color to an HSV color.
+     *
+     * @returns An HSV instance representing the same color.
+     */
     asHSV(): HSV;
+    /**
+     * Returns the RGB color.
+     *
+     * @returns The current RGB instance.
+     */
     asRGB(): RGB;
+    /**
+     * Returns the RGB color.
+     *
+     * @returns The current RGB instance.
+     */
     toRGB(): RGB;
+    /**
+     * Parses a string or Color instance into an RGB color.
+     *
+     * @param input - The input string or Color instance to parse.
+     * @returns A new RGB instance representing the parsed color.
+     * @throws Will throw an error if the input string is not a valid RGB color string.
+     */
     static parse(input: string | Color): RGB;
+    /**
+     * Adjusts the gamma of the RGB color.
+     *
+     * @param value - The gamma value to apply.
+     * @returns A new RGB instance with the adjusted gamma.
+     */
     gamma(value: number): RGB;
+    /**
+     * Inverts the RGB color.
+     *
+     * @returns A new RGB instance with the inverted color values.
+     */
     invert(): RGB;
+    /**
+     * Adjusts the contrast of the RGB color.
+     *
+     * @param value - The contrast value to apply.
+     * @returns A new RGB instance with the adjusted contrast.
+     */
     contrast(value: number): RGB;
+    /**
+     * Adjusts the brightness of the RGB color.
+     *
+     * @param value - The brightness value to apply.
+     * @returns A new RGB instance with the adjusted brightness.
+     */
     brightness(value: number): RGB;
+    /**
+     * Tints the RGB color with another color.
+     *
+     * @param value - The tint value to apply.
+     * @param tintColor - The color to use for tinting.
+     * @returns A new RGB instance with the applied tint.
+     */
     tint(value: number, tintColor: Color): RGB;
+    /**
+     * Blends the RGB color with another color.
+     *
+     * @param value - The blend value to apply.
+     * @param blendColor - The color to blend with.
+     * @returns A new RGB instance with the blended color.
+     */
     blend(value: number, blendColor: Color): RGB;
+    /**
+     * Lightens the RGB color.
+     *
+     * @param ratio - The ratio to lighten the color by.
+     * @returns A new RGB instance with the lightened color.
+     */
     lighten(ratio: number): RGB;
+    /**
+     * Darkens the RGB color.
+     *
+     * @param ratio - The ratio to darken the color by.
+     * @returns A new RGB instance with the darkened color.
+     */
     darken(ratio: number): RGB;
+    /**
+     * Fades the RGB color by reducing its alpha value.
+     *
+     * @param value - The fade value to apply.
+     * @returns A new RGB instance with the faded color.
+     */
     fade(value: number): RGB;
 }
 
+/**
+ * Represents a color in the HSV (Hue, Saturation, Value) color space.
+ * Extends the base `Color` class.
+ */
 declare class HSV extends Color {
+    /**
+     * The hue component of the color, in the range [0, 360].
+     */
     readonly h: number;
+    /**
+     * The saturation component of the color, in the range [0, 100].
+     */
     readonly s: number;
+    /**
+     * The value (brightness) component of the color, in the range [0, 100].
+     */
     readonly v: number;
+    /**
+     * The alpha (opacity) component of the color, in the range [0, 1].
+     */
     readonly a: number;
+    /**
+     * Constructs a new HSV color.
+     * @param h - The hue component, in the range [0, 360].
+     * @param s - The saturation component, in the range [0, 100].
+     * @param v - The value (brightness) component, in the range [0, 100].
+     * @param a - The alpha (opacity) component, in the range [0, 1]. Defaults to 1.
+     */
     constructor(h: number, s: number, v: number, a?: number);
+    /**
+     * Returns the HSV color as an array of numbers.
+     * @returns An array containing the hue, saturation, value, and alpha components.
+     */
     asArray(): [number, number, number, number];
+    /**
+     * Returns a new HSV color with the components rounded to the nearest integer.
+     * @returns A new HSV color with rounded components.
+     */
     round(): HSV;
+    /**
+     * Returns the color as a string representation.
+     * @returns A string representation of the color.
+     */
     asString(): string;
+    /**
+     * Creates a new HSV color that is a copy of the current color.
+     * @returns A new HSV color that is a clone of the current color.
+     */
     clone(): HSV;
+    /**
+     * Converts the HSV color to an HSL color.
+     * @returns An HSL representation of the color.
+     */
     asHSL(): HSL;
+    /**
+     * Returns the current HSV color.
+     * @returns The current HSV color.
+     */
     asHSV(): HSV;
+    /**
+     * Returns the current HSV color.
+     * @returns The current HSV color.
+     */
     toHSV(): HSV;
+    /**
+     * Converts the HSV color to an RGB color.
+     * @returns An RGB representation of the color.
+     */
     asRGB(): RGB;
+    /**
+     * Fades the color by a given value.
+     * @param value - The amount to fade the color by, in the range [0, 1].
+     * @returns A new HSV color with the alpha component faded by the given value.
+     */
     fade(value: number): HSV;
+    /**
+     * Sets the hue component of the color.
+     * @param value - The new hue value, in the range [0, 360].
+     * @returns A new HSV color with the updated hue component.
+     */
     setHue(value: number): HSV;
+    static randomColor(options?: RandomColorOptions): HSV;
 }
 
+/**
+ * Represents a color in the HSL (Hue, Saturation, Lightness) color space.
+ * Extends the base `Color` class.
+ */
 declare class HSL extends Color {
+    /**
+     * The hue component of the color, in the range [0, 360].
+     */
     readonly h: number;
+    /**
+     * The saturation component of the color, in the range [0, 100].
+     */
     readonly s: number;
+    /**
+     * The lightness component of the color, in the range [0, 100].
+     */
     readonly l: number;
+    /**
+     * The alpha (opacity) component of the color, in the range [0, 1].
+     */
     readonly a: number;
+    /**
+     * Creates a new HSL color.
+     * @param h - The hue component, in the range [0, 360].
+     * @param s - The saturation component, in the range [0, 100].
+     * @param l - The lightness component, in the range [0, 100].
+     * @param a - The alpha (opacity) component, in the range [0, 1]. Defaults to 1.
+     */
     constructor(h: number, s: number, l: number, a?: number);
+    /**
+     * Returns the HSL color as an array of numbers.
+     * @returns An array containing the hue, saturation, lightness, and alpha components.
+     */
     asArray(): [number, number, number, number];
+    /**
+     * Returns a new HSL color with rounded components.
+     * @returns A new HSL color with rounded hue, saturation, lightness, and alpha components.
+     */
     round(): HSL;
+    /**
+     * Creates a copy of the current HSL color.
+     * @returns A new HSL color with the same components as the current color.
+     */
     clone(): HSL;
+    /**
+     * Returns the HSL color as a CSS-compatible string.
+     * @returns A string representing the HSL color in CSS format.
+     */
     asString(): string;
+    /**
+     * Returns the current HSL color.
+     * @returns The current HSL color.
+     */
     asHSL(): HSL;
+    /**
+     * Returns the current HSL color.
+     * @returns The current HSL color.
+     */
     toHSL(): HSL;
+    /**
+     * Converts the HSL color to an HSV color.
+     * @returns A new HSV color representing the same color.
+     */
     asHSV(): HSV;
+    /**
+     * Converts the HSL color to an RGB color.
+     * @returns A new RGB color representing the same color.
+     */
     asRGB(): RGB;
+    /**
+     * Parses a string or Color object into an HSL color.
+     * @param input - The input string or Color object to parse.
+     * @returns A new HSL color parsed from the input.
+     * @throws Will throw an error if the input string is not a valid HSL color string.
+     */
     static parse(input: string | Color): HSL;
+    /**
+     * Inverts the lightness component of the HSL color.
+     * @returns A new HSL color with the lightness component inverted.
+     */
     invertLuminosity(): HSL;
+    /**
+     * Rotates the hue component of the HSL color by a given offset.
+     * @param offset - The amount to rotate the hue by, in degrees.
+     * @returns A new HSL color with the hue rotated by the given offset.
+     */
     rotateHue(offset: number): HSL;
+    /**
+     * Increases the saturation of the HSL color by a given ratio.
+     * @param ratio - The ratio by which to increase the saturation.
+     * @returns A new HSL color with increased saturation.
+     */
     saturate(ratio: number): HSL;
+    /**
+     * Decreases the alpha (opacity) of the HSL color by a given value.
+     * @param value - The value by which to decrease the alpha.
+     * @returns A new HSL color with decreased alpha.
+     */
     fade(value: number): HSL;
 }
 
-interface RandomColorOptions {
-    seed?: string;
-    hue?: number | string;
-    opacity?: number;
-    luminosity?: number | string;
-    saturation?: number | string;
-}
-
+/**
+ * The abstract `Color` class provides a blueprint for color manipulation and conversion.
+ * It includes methods for converting between different color models ({@link HSL}, {@link HSV}, {@link RGB}),
+ * as well as various color transformations such as inversion, rotation, saturation, and blending.
+ *
+ * @abstract
+ */
+/**
+ * Abstract class representing a color.
+ */
 declare abstract class Color {
+    /**
+     * Parses a color from a string or another Color instance.
+     * @param input - The input color as a string or Color instance.
+     * @returns The parsed Color instance.
+     */
     static parse: (input: Color | string) => Color;
+    /**
+     * The HSL color model.
+     */
     static HSL: typeof HSL;
+    /**
+     * The HSV color model.
+     */
     static HSV: typeof HSV;
+    /**
+     * The RGB color model.
+     */
     static RGB: typeof RGB;
-    static random: (options?: RandomColorOptions) => HSV;
+    /**
+     * Creates a clone of the current color instance.
+     * @returns A new Color instance that is a clone of the current instance.
+     */
     abstract clone(): Color;
+    /**
+     * Converts the color to a hexadecimal string.
+     * @returns The hexadecimal representation of the color.
+     */
     asHex(): string;
+    /**
+     * Converts the color to a string representation.
+     * @returns The string representation of the color.
+     */
     abstract asString(): string;
+    /**
+     * Rounds the color values.
+     * @returns A new Color instance with rounded values.
+     */
     abstract round(): Color;
+    /**
+     * Converts the color to an array of numbers.
+     * @returns An array representing the color.
+     */
     abstract asArray(): number[];
+    /**
+     * Converts the color to the HSL color model.
+     * @returns The HSL representation of the color.
+     */
     abstract asHSL(): HSL;
+    /**
+     * Converts the color to the HSV color model.
+     * @returns The HSV representation of the color.
+     */
     abstract asHSV(): HSV;
+    /**
+     * Converts the color to the RGB color model.
+     * @returns The RGB representation of the color.
+     */
     abstract asRGB(): RGB;
-    toHSL(): HSL;
-    toHSV(): HSV;
-    toRGB(): RGB;
+    /**
+     * Inverts the luminosity of the color.
+     * @returns A new HSL color with inverted luminosity.
+     */
     invertLuminosity(): HSL;
+    /**
+     * Rotates the hue of the color by a given offset.
+     * @param offset - The amount to rotate the hue.
+     * @returns A new HSL color with the hue rotated.
+     */
     rotateHue(offset: number): HSL;
+    /**
+     * Saturates the color by a given ratio.
+     * @param ratio - The ratio to saturate the color.
+     * @returns A new HSL color with increased saturation.
+     */
     saturate(ratio: number): HSL;
+    /**
+     * Applies gamma correction to the color.
+     * @param value - The gamma correction value.
+     * @returns A new RGB color with gamma correction applied.
+     */
     gamma(value: number): RGB;
+    /**
+     * Inverts the color.
+     * @returns A new RGB color with inverted values.
+     */
     invert(): RGB;
+    /**
+     * Adjusts the contrast of the color.
+     * @param value - The contrast adjustment value.
+     * @returns A new RGB color with adjusted contrast.
+     */
     contrast(value: number): RGB;
+    /**
+     * Adjusts the brightness of the color.
+     * @param value - The brightness adjustment value.
+     * @returns A new RGB color with adjusted brightness.
+     */
     brightness(value: number): RGB;
+    /**
+     * Lightens the color by a given value.
+     * @param value - The amount to lighten the color.
+     * @returns A new RGB color that is lightened.
+     */
     lighten(value: number): RGB;
+    /**
+     * Darkens the color by a given value.
+     * @param value - The amount to darken the color.
+     * @returns A new RGB color that is darkened.
+     */
     darken(value: number): RGB;
+    /**
+     * Tints the color by blending it with another color.
+     * @param value - The blend ratio.
+     * @param tintColor - The color to blend with.
+     * @returns A new RGB color that is tinted.
+     */
     tint(value: number, tintColor: Color): RGB;
+    /**
+     * Blends the color with another color.
+     * @param value - The blend ratio.
+     * @param blendColor - The color to blend with.
+     * @returns A new RGB color that is blended.
+     */
     blend(value: number, blendColor: Color): RGB;
+    /**
+     * Sets the hue of the color.
+     * @param value - The new hue value.
+     * @returns A new HSV color with the hue set.
+     */
     setHue(value: number): HSV;
+    /**
+     * Fades the color by a given value.
+     * @param value - The fade value.
+     * @returns A new Color instance that is faded.
+     */
     abstract fade(value: number): Color;
 }
 
@@ -128,22 +524,22 @@ declare abstract class Color {
  *
  * ```typescript
  * const style = VersaTilesStyle.colorful({
- *    recolor: {
- *       rotate: 180,
- *       saturate: 0.5,
- *       brightness: 0.2,
- *    }
+ *   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
- *    }
+ *   recolor: {
+ *     blend: 0.5,
+ *     blendColor: '#000000', // to blend all colors with black
+ *     // or blendColor: '#FFFFFF', // to blend all colors with white
+ *   }
  * };
  * ```
  *
@@ -214,102 +610,66 @@ interface RecolorOptions {
 
 /** Represents language suffixes used in map styles. */
 type Language = 'de' | 'en' | null;
-/** Options for configuring a style builder. */
+/**
+ * Options for configuring the style builder.
+ */
 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]
+     * @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;
 }
+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';
 /** Records string values for color properties in a style builder. */
-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;
-}
-type StyleBuilderColorsEnsured = Record<keyof StyleBuilderColors, Color>;
+type StyleBuilderColors<T = Color | string> = Record<StyleBuilderColorKey, T>;
 /** Records string values for font properties in a style builder. */
 type StyleBuilderFonts = {
     regular: string;
@@ -323,6 +683,7 @@ interface StyleBuilderFunction {
 declare const colorful: StyleBuilderFunction;
 declare const eclipse: StyleBuilderFunction;
 declare const graybeard: StyleBuilderFunction;
+declare const shadow: StyleBuilderFunction;
 declare const neutrino: StyleBuilderFunction;
 
 /** Represents the structure of a vector layer in a TileJSON specification. */
@@ -360,18 +721,43 @@ interface TileJSONSpecificationVector extends TileJSONSpecificationRaster {
 /** Represents a TileJSON specification, which can be either raster or vector. */
 type TileJSONSpecification = TileJSONSpecificationRaster | TileJSONSpecificationVector;
 
+/**
+ * Options for guessing the style of a map.
+ */
 interface GuessStyleOptions {
+    /**
+     * Base URL to resolve URLs for tile sources, glyphs, and sprites.
+     */
     baseUrl?: string;
+    /**
+     * URL template for glyphs.
+     */
     glyphs?: string;
+    /**
+     * URL template for sprites. See also {@link SpriteSpecification}.
+     */
     sprite?: SpriteSpecification;
 }
+/**
+ * Generates a style specification based on the provided TileJSON specification and optional parameters.
+ *
+ * @param {TileJSONSpecification} tileJSON - The TileJSON specification to generate the style from.
+ * @param {GuessStyleOptions} [options] - Optional parameters to customize the style generation.
+ * @param {string} [options.baseUrl] - Base URL to resolve tile URLs.
+ * @param {string} [options.glyphs] - URL template for glyphs.
+ * @param {string} [options.sprite] - URL template for sprites.
+ * @returns {StyleSpecification} The generated style specification.
+ * @throws {Error} If the provided TileJSON specification is invalid.
+ */
 declare function guessStyle(tileJSON: TileJSONSpecification, options?: GuessStyleOptions): StyleSpecification;
 
 declare const styles: {
     colorful: StyleBuilderFunction;
     eclipse: StyleBuilderFunction;
     graybeard: StyleBuilderFunction;
+    shadow: StyleBuilderFunction;
     neutrino: StyleBuilderFunction;
 };
 
-export { Color, type GuessStyleOptions, HSL, HSV, type Language, RGB, type RandomColorOptions, type RecolorOptions, type StyleBuilderColors, type StyleBuilderColorsEnsured, type StyleBuilderFonts, type StyleBuilderFunction, type StyleBuilderOptions, type TileJSONSpecification, type TileJSONSpecificationRaster, type TileJSONSpecificationVector, type VectorLayer, colorful, eclipse, graybeard, guessStyle, neutrino, styles };
+export { Color, HSL, HSV, RGB, colorful, eclipse, graybeard, guessStyle, neutrino, shadow, styles };
+export type { GuessStyleOptions, Language, RandomColorOptions, RecolorOptions, StyleBuilderColorKey, StyleBuilderColors, StyleBuilderFonts, StyleBuilderFunction, StyleBuilderOptions, TileJSONSpecification, TileJSONSpecificationRaster, TileJSONSpecificationVector, VectorLayer };