tessl/npm-mapbox--mapbox-gl-style-spec

Specification and utilities for working with Mapbox GL styles including validation, migration, formatting, and expression evaluation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Color Utilities

Name: tessl/npm-mapbox--mapbox-gl-style-spec
Author: tessl

Comprehensive color manipulation and conversion utilities supporting multiple color formats including CSS colors, RGBA, HSL, and specialized rendering formats for map styling.

Capabilities

Color Class

Main color manipulation class providing parsing, conversion, and arithmetic operations.

/**
 * Main color class for parsing and manipulating colors
 * @param r - Red component (0-1)
 * @param g - Green component (0-1)  
 * @param b - Blue component (0-1)
 * @param a - Alpha component (0-1, default: 1)
 */
class Color {
  constructor(r: number, g: number, b: number, a?: number);
  
  /** Red component (0-1) */
  readonly r: number;
  /** Green component (0-1) */
  readonly g: number;
  /** Blue component (0-1) */
  readonly b: number;
  /** Alpha component (0-1) */
  readonly a: number;

  /**
   * Parses a CSS color string into a Color instance
   * @param input - CSS color string (hex, rgb, rgba, hsl, hsla, named colors)
   * @returns Color instance or undefined if parsing fails
   */
  static parse(input: string): Color | undefined;

  /**
   * Converts color to RGBA string representation
   * @returns RGBA string format "rgba(r, g, b, a)"
   */
  toString(): string;

  /**
   * Creates a deep copy of the color
   * @returns New Color instance with same values
   */
  clone(): Color;

  // Predefined color constants
  static readonly black: Color;
  static readonly white: Color;
  static readonly transparent: Color;
  static readonly red: Color;
  static readonly blue: Color;
}

Usage Examples:

import { Color } from "@mapbox/mapbox-gl-style-spec";

// Create colors from components
const red = new Color(1, 0, 0, 1);
const semiTransparent = new Color(0.5, 0.5, 0.5, 0.8);

// Parse CSS color strings
const parsed1 = Color.parse('#ff0000');        // Hex
const parsed2 = Color.parse('rgb(255, 0, 0)'); // RGB
const parsed3 = Color.parse('rgba(255, 0, 0, 0.5)'); // RGBA
const parsed4 = Color.parse('hsl(0, 100%, 50%)');    // HSL
const parsed5 = Color.parse('red');                  // Named color

// Use predefined colors
const black = Color.black;
const white = Color.white;
const transparent = Color.transparent;

// Convert to string
console.log(red.toString()); // "rgba(255, 0, 0, 1)"

// Clone colors
const redCopy = red.clone();

Render Color Classes

Specialized color classes for different rendering contexts with alpha channel handling.

/**
 * Abstract base class for renderable colors
 */
abstract class RenderColor {
  readonly r: number;
  readonly g: number;
  readonly b: number;
  readonly a: number;

  constructor(r: number, g: number, b: number, a: number);
  
  /**
   * Converts to array representation for rendering
   * @returns RGBA array [r, g, b, a]
   */
  abstract toArray(): [number, number, number, number];
}

/**
 * Color with non-premultiplied alpha for standard rendering
 */
class NonPremultipliedRenderColor extends RenderColor {
  /**
   * @param lut - Lookup table for color transformation (can be null)
   * @param r - Red component (0-1)
   * @param g - Green component (0-1)
   * @param b - Blue component (0-1) 
   * @param a - Alpha component (0-1)
   */
  constructor(lut: LUT | null, r: number, g: number, b: number, a: number);
  
  toArray(): [number, number, number, number];
}

/**
 * Color with premultiplied alpha for optimized rendering
 */
class PremultipliedRenderColor extends RenderColor {
  /**
   * @param lut - Lookup table for color transformation (can be null)
   * @param r - Red component (0-1)
   * @param g - Green component (0-1)
   * @param b - Blue component (0-1)
   * @param a - Alpha component (0-1)
   */
  constructor(lut: LUT | null, r: number, g: number, b: number, a: number);
  
  toArray(): [number, number, number, number];
}

Usage Examples:

import { NonPremultipliedRenderColor, PremultipliedRenderColor } from "@mapbox/mapbox-gl-style-spec";

// Standard rendering color (no LUT)
const standardColor = new NonPremultipliedRenderColor(null, 1, 0, 0, 0.5);
console.log(standardColor.toArray()); // [1, 0, 0, 0.5]

// Optimized rendering color with premultiplied alpha (no LUT)
const premultColor = new PremultipliedRenderColor(null, 0.5, 0, 0, 0.5);
console.log(premultColor.toArray()); // [0.5, 0, 0, 0.5]

Color Format Support

Supported Input Formats

The Color.parse() method supports a wide range of CSS color formats:

// Hex formats
Color.parse('#ff0000');     // 6-digit hex
Color.parse('#f00');        // 3-digit hex
Color.parse('#ff0000ff');   // 8-digit hex with alpha
Color.parse('#f00f');       // 4-digit hex with alpha

// RGB/RGBA formats
Color.parse('rgb(255, 0, 0)');
Color.parse('rgba(255, 0, 0, 0.5)');
Color.parse('rgb(100%, 0%, 0%)');      // Percentage values
Color.parse('rgba(100%, 0%, 0%, 50%)');

// HSL/HSLA formats
Color.parse('hsl(0, 100%, 50%)');
Color.parse('hsla(0, 100%, 50%, 0.5)');

// Named colors
Color.parse('red');
Color.parse('blue');
Color.parse('transparent');
Color.parse('aliceblue');

Usage Examples:

import { Color } from "@mapbox/mapbox-gl-style-spec";

// Parse various formats
const colors = [
  Color.parse('#3388ff'),
  Color.parse('rgb(51, 136, 255)'),
  Color.parse('hsl(215, 100%, 60%)'),
  Color.parse('cornflowerblue')
].filter(Boolean); // Remove any failed parses

// Convert all to consistent format
colors.forEach(color => {
  console.log(color.toString()); // All output as rgba() strings
});

Color Space Operations

While the core Color class focuses on RGBA, the package includes utilities for color space conversions and interpolations:

// Color interpolation utilities (from util/interpolate.ts)
interface ColorInterpolationUtilities {
  /** Interpolate between colors in RGB space */
  interpolateRGB(from: Color, to: Color, t: number): Color;
  
  /** Interpolate between colors in HSL space */
  interpolateHSL(from: Color, to: Color, t: number): Color;
  
  /** Interpolate between colors in LAB space */
  interpolateLAB(from: Color, to: Color, t: number): Color;
}

Integration with Style Properties

Color Property Values

Colors integrate seamlessly with style property specifications:

type ColorSpecification = string;

// Usage in layer properties
interface LayerPaintProperties {
  'background-color'?: ColorSpecification;
  'fill-color'?: PropertyValueSpecification<ColorSpecification>;
  'line-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
  'text-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
  'icon-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
}

Usage Examples:

// Static colors in layer properties
const layer = {
  id: 'buildings',
  type: 'fill',
  paint: {
    'fill-color': '#ff0000',           // Hex
    'fill-outline-color': 'rgba(0,0,0,0.5)', // RGBA
  }
};

// Dynamic colors with expressions
const dynamicLayer = {
  id: 'population',
  type: 'fill', 
  paint: {
    'fill-color': [
      'interpolate',
      ['linear'],
      ['get', 'population'],
      0, '#ffffcc',
      1000, '#c2e699', 
      5000, '#78c679',
      10000, '#238443'
    ]
  }
};

Types

interface ColorComponents {
  r: number; // Red (0-1)
  g: number; // Green (0-1)
  b: number; // Blue (0-1)
  a: number; // Alpha (0-1)
}

type ColorSpecification = string;

type LUT = any; // Lookup table for color transformations

interface ColorParseResult {
  success: boolean;
  color?: Color;
  error?: string;
}