@carto/ps-utils 2.0.1 → 2.1.0

package/src/colors/carto-palettes/carto-palettes.ts

@@ -0,0 +1,355 @@
+/**
+ * CARTOColors palettes (name -> hex ramp), full CARTO-native set: sequential
+ * (incl. aggregation), diverging and qualitative. Each entry is the palette's
+ * largest class-count ramp, verbatim. Kept inline so the package stays
+ * zero-dependency; ColorBrewer (`cb_*`) palettes are intentionally excluded.
+ *
+ * Data: CARTOColors - https://github.com/CartoDB/cartocolor - CC-BY-4.0.
+ * Generated from cartocolor@5.0.2 (unmodified beyond taking each max ramp).
+ */
+export const CARTO_PALETTES = {
+  // Sequential (+ aggregation)
+  ag_GrnYl: [
+    '#245668',
+    '#0F7279',
+    '#0D8F81',
+    '#39AB7E',
+    '#6EC574',
+    '#A9DC67',
+    '#EDEF5D',
+  ],
+  ag_Sunset: [
+    '#4b2991',
+    '#872ca2',
+    '#c0369d',
+    '#ea4f88',
+    '#fa7876',
+    '#f6a97a',
+    '#edd9a3',
+  ],
+  BluGrn: [
+    '#c4e6c3',
+    '#96d2a4',
+    '#6dbc90',
+    '#4da284',
+    '#36877a',
+    '#266b6e',
+    '#1d4f60',
+  ],
+  BluYl: [
+    '#f7feae',
+    '#b7e6a5',
+    '#7ccba2',
+    '#46aea0',
+    '#089099',
+    '#00718b',
+    '#045275',
+  ],
+  BrwnYl: [
+    '#ede5cf',
+    '#e0c2a2',
+    '#d39c83',
+    '#c1766f',
+    '#a65461',
+    '#813753',
+    '#541f3f',
+  ],
+  Burg: [
+    '#ffc6c4',
+    '#f4a3a8',
+    '#e38191',
+    '#cc607d',
+    '#ad466c',
+    '#8b3058',
+    '#672044',
+  ],
+  BurgYl: [
+    '#fbe6c5',
+    '#f5ba98',
+    '#ee8a82',
+    '#dc7176',
+    '#c8586c',
+    '#9c3f5d',
+    '#70284a',
+  ],
+  DarkMint: [
+    '#d2fbd4',
+    '#a5dbc2',
+    '#7bbcb0',
+    '#559c9e',
+    '#3a7c89',
+    '#235d72',
+    '#123f5a',
+  ],
+  Emrld: [
+    '#d3f2a3',
+    '#97e196',
+    '#6cc08b',
+    '#4c9b82',
+    '#217a79',
+    '#105965',
+    '#074050',
+  ],
+  Magenta: [
+    '#f3cbd3',
+    '#eaa9bd',
+    '#dd88ac',
+    '#ca699d',
+    '#b14d8e',
+    '#91357d',
+    '#6c2167',
+  ],
+  Mint: [
+    '#e4f1e1',
+    '#b4d9cc',
+    '#89c0b6',
+    '#63a6a0',
+    '#448c8a',
+    '#287274',
+    '#0d585f',
+  ],
+  OrYel: [
+    '#ecda9a',
+    '#efc47e',
+    '#f3ad6a',
+    '#f7945d',
+    '#f97b57',
+    '#f66356',
+    '#ee4d5a',
+  ],
+  Peach: [
+    '#fde0c5',
+    '#facba6',
+    '#f8b58b',
+    '#f59e72',
+    '#f2855d',
+    '#ef6a4c',
+    '#eb4a40',
+  ],
+  PinkYl: [
+    '#fef6b5',
+    '#ffdd9a',
+    '#ffc285',
+    '#ffa679',
+    '#fa8a76',
+    '#f16d7a',
+    '#e15383',
+  ],
+  Purp: [
+    '#f3e0f7',
+    '#e4c7f1',
+    '#d1afe8',
+    '#b998dd',
+    '#9f82ce',
+    '#826dba',
+    '#63589f',
+  ],
+  PurpOr: [
+    '#f9ddda',
+    '#f2b9c4',
+    '#e597b9',
+    '#ce78b3',
+    '#ad5fad',
+    '#834ba0',
+    '#573b88',
+  ],
+  RedOr: [
+    '#f6d2a9',
+    '#f5b78e',
+    '#f19c7c',
+    '#ea8171',
+    '#dd686c',
+    '#ca5268',
+    '#b13f64',
+  ],
+  Sunset: [
+    '#f3e79b',
+    '#fac484',
+    '#f8a07e',
+    '#eb7f86',
+    '#ce6693',
+    '#a059a0',
+    '#5c53a5',
+  ],
+  SunsetDark: [
+    '#fcde9c',
+    '#faa476',
+    '#f0746e',
+    '#e34f6f',
+    '#dc3977',
+    '#b9257a',
+    '#7c1d6f',
+  ],
+  Teal: [
+    '#d1eeea',
+    '#a8dbd9',
+    '#85c4c9',
+    '#68abb8',
+    '#4f90a6',
+    '#3b738f',
+    '#2a5674',
+  ],
+  TealGrn: [
+    '#b0f2bc',
+    '#89e8ac',
+    '#67dba5',
+    '#4cc8a3',
+    '#38b2a3',
+    '#2c98a0',
+    '#257d98',
+  ],
+
+  // Diverging
+  ArmyRose: [
+    '#798234',
+    '#a3ad62',
+    '#d0d3a2',
+    '#fdfbe4',
+    '#f0c6c3',
+    '#df91a3',
+    '#d46780',
+  ],
+  Earth: [
+    '#A16928',
+    '#bd925a',
+    '#d6bd8d',
+    '#edeac2',
+    '#b5c8b8',
+    '#79a7ac',
+    '#2887a1',
+  ],
+  Fall: [
+    '#3d5941',
+    '#778868',
+    '#b5b991',
+    '#f6edbd',
+    '#edbb8a',
+    '#de8a5a',
+    '#ca562c',
+  ],
+  Geyser: [
+    '#008080',
+    '#70a494',
+    '#b4c8a8',
+    '#f6edbd',
+    '#edbb8a',
+    '#de8a5a',
+    '#ca562c',
+  ],
+  TealRose: [
+    '#009392',
+    '#72aaa1',
+    '#b1c7b3',
+    '#f1eac8',
+    '#e5b9ad',
+    '#d98994',
+    '#d0587e',
+  ],
+  Temps: [
+    '#009392',
+    '#39b185',
+    '#9ccb86',
+    '#e9e29c',
+    '#eeb479',
+    '#e88471',
+    '#cf597e',
+  ],
+  Tropic: [
+    '#009B9E',
+    '#42B7B9',
+    '#A7D3D4',
+    '#F1F1F1',
+    '#E4C1D9',
+    '#D691C1',
+    '#C75DAB',
+  ],
+
+  // Qualitative
+  Antique: [
+    '#855C75',
+    '#D9AF6B',
+    '#AF6458',
+    '#736F4C',
+    '#526A83',
+    '#625377',
+    '#68855C',
+    '#9C9C5E',
+    '#A06177',
+    '#8C785D',
+    '#467378',
+    '#7C7C7C',
+  ],
+  Bold: [
+    '#7F3C8D',
+    '#11A579',
+    '#3969AC',
+    '#F2B701',
+    '#E73F74',
+    '#80BA5A',
+    '#E68310',
+    '#008695',
+    '#CF1C90',
+    '#f97b72',
+    '#4b4b8f',
+    '#A5AA99',
+  ],
+  Pastel: [
+    '#66C5CC',
+    '#F6CF71',
+    '#F89C74',
+    '#DCB0F2',
+    '#87C55F',
+    '#9EB9F3',
+    '#FE88B1',
+    '#C9DB74',
+    '#8BE0A4',
+    '#B497E7',
+    '#D3B484',
+    '#B3B3B3',
+  ],
+  Prism: [
+    '#5F4690',
+    '#1D6996',
+    '#38A6A5',
+    '#0F8554',
+    '#73AF48',
+    '#EDAD08',
+    '#E17C05',
+    '#CC503E',
+    '#94346E',
+    '#6F4070',
+    '#994E95',
+    '#666666',
+  ],
+  Safe: [
+    '#88CCEE',
+    '#CC6677',
+    '#DDCC77',
+    '#117733',
+    '#332288',
+    '#AA4499',
+    '#44AA99',
+    '#999933',
+    '#882255',
+    '#661100',
+    '#6699CC',
+    '#888888',
+  ],
+  Vivid: [
+    '#E58606',
+    '#5D69B1',
+    '#52BCA3',
+    '#99C945',
+    '#CC61B0',
+    '#24796C',
+    '#DAA51B',
+    '#2F8AC4',
+    '#764E9F',
+    '#ED645A',
+    '#CC3A8E',
+    '#A5AA99',
+  ],
+} satisfies Record<string, readonly string[]>
+
+/** A known CARTOColors palette name. */
+export type PaletteName = keyof typeof CARTO_PALETTES

package/src/colors/hex-to-rgba/hex-to-rgba.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test, vi } from 'vitest'
+import { hexToRgba } from './hex-to-rgba'
+
+describe.each([
+  { hex: '#000000', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '#000', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '#00', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '000000', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '000', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '00', op: 0, expected: [0, 0, 0, 0] },
+  { hex: '#ff', op: 0, expected: [255, 255, 255, 0] },
+  { hex: '#fff', op: 0, expected: [255, 255, 255, 0] },
+  { hex: '#ffffff', op: 0, expected: [255, 255, 255, 0] },
+  { hex: '#ffffff', op: 0.5, expected: [255, 255, 255, 127.5] },
+  { hex: '#ffffff', op: 0.1, expected: [255, 255, 255, 25.5] },
+  { hex: '#ffffff', op: 0.75, expected: [255, 255, 255, 191.25] },
+  { hex: 'ffffff', op: 0.75, expected: [255, 255, 255, 191.25] },
+  { hex: '#abc', op: 1, expected: [171, 202, 188, 255] },
+  { hex: 'abc', op: 0.5, expected: [171, 202, 188, 127.5] },
+  { hex: '#123456', op: 1, expected: [18, 52, 86, 255] },
+  { hex: '123456', op: 0, expected: [18, 52, 86, 0] },
+  { hex: '#a1', op: 1, expected: [161, 161, 161, 255] },
+  { hex: 'a1', op: 0.5, expected: [161, 161, 161, 127.5] },
+])('hexToRgba(%s, %i)', ({ hex, op, expected }) => {
+  test(`returns ${JSON.stringify(expected)}`, () => {
+    expect(hexToRgba(hex, op)).toEqual(expected)
+  })
+})
+
+describe.each([
+  { hex: '#000000', op: -1, error: 'hexToRgba: -1 invalid alpha format' },
+  {
+    hex: '#000000',
+    op: 1.1,
+    error: 'hexToRgba: 1.1 invalid alpha format',
+  },
+  {
+    hex: 'null',
+    op: 0,
+    error: 'hexToRgba: null invalid hexadecimal format',
+  },
+  {
+    hex: null,
+    op: 0,
+    error: 'hexToRgba: null invalid hexadecimal format',
+  },
+  {
+    hex: 'nul',
+    op: 0,
+    error: 'hexToRgba: nul invalid hexadecimal format',
+  },
+  {
+    hex: '',
+    op: 0,
+    error: 'hexToRgba:  invalid hexadecimal format',
+  },
+  {
+    hex: 'gggggg',
+    op: 1,
+    error: 'hexToRgba: gggggg invalid hexadecimal format',
+  },
+])('hexToRgba fails', ({ hex, op, error }) => {
+  test(`returns ${error}`, () => {
+    const err = vi.spyOn(console, 'warn').mockImplementation(() => vi.fn())
+    expect(hexToRgba(hex!, op)).toBeUndefined()
+    expect(err).toHaveBeenLastCalledWith(error)
+  })
+})
+
+describe('hexToRgba with default alpha', () => {
+  test('should use default alpha value of 1', () => {
+    expect(hexToRgba('#ffffff')).toEqual([255, 255, 255, 255])
+  })
+
+  test('should use default alpha value of 1 for 3-digit hex', () => {
+    expect(hexToRgba('#abc')).toEqual([171, 202, 188, 255])
+  })
+
+  test('should use default alpha value of 1 for 2-digit hex', () => {
+    expect(hexToRgba('#ff')).toEqual([255, 255, 255, 255])
+  })
+})

package/src/colors/hex-to-rgba/hex-to-rgba.ts

@@ -0,0 +1,67 @@
+/**
+ * Converts a hexadecimal color string to an RGBA array, useful for deck.gl layer styling and canvas operations.
+ *
+ * @param hexadecimal - Hex color string (supports `#ffffff`, `ffffff`, `#fff`, `fff`, `#ff` formats).
+ * @param alpha - Opacity level from 0 (transparent) to 1 (opaque). Default is `1`.
+ * @returns An `[r, g, b, a]` array with values 0-255, or `undefined` for invalid inputs.
+ *
+ * @example
+ * ```ts
+ * hexToRgba('#ff0000', 0.8) // [255, 0, 0, 204]
+ * hexToRgba('#f00', 0.5)    // [255, 0, 0, 127.5]
+ * hexToRgba('00ff00')       // [0, 255, 0, 255]
+ * ```
+ */
+export function hexToRgba(
+  hexadecimal: string,
+  alpha = 1,
+): [number, number, number, number] | undefined {
+  if (!hexadecimal) {
+    // eslint-disable-next-line no-console
+    console.warn(`hexToRgba: ${hexadecimal} invalid hexadecimal format`)
+    return
+  }
+  if (alpha < 0 || alpha > 1) {
+    // eslint-disable-next-line no-console
+    console.warn(`hexToRgba: ${alpha} invalid alpha format`)
+    return
+  }
+  if (hexadecimal?.includes('#')) {
+    hexadecimal = hexadecimal.slice(1)
+  }
+  if (
+    !/[0-9A-Fa-f]{6}/g.test(hexadecimal) &&
+    !/[0-9A-Fa-f]{3}/g.test(hexadecimal) &&
+    !/[0-9A-Fa-f]{2}/g.test(hexadecimal)
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(`hexToRgba: ${hexadecimal} invalid hexadecimal format`)
+    return
+  }
+
+  const length = hexadecimal.length
+
+  if (length < 6) {
+    hexadecimal = hexadecimal.slice(0, 6 - length).repeat(6 / length)
+  }
+
+  const r = parseInt(
+    hexadecimal.length === 3
+      ? hexadecimal.slice(0, 1).repeat(2)
+      : hexadecimal.slice(0, 2),
+    16,
+  )
+  const g = parseInt(
+    hexadecimal.length === 3
+      ? hexadecimal.slice(1, 2).repeat(2)
+      : hexadecimal.slice(2, 4),
+    16,
+  )
+  const b = parseInt(
+    hexadecimal.length === 3
+      ? hexadecimal.slice(2, 3).repeat(2)
+      : hexadecimal.slice(4, 6),
+    16,
+  )
+  return [r, g, b, alpha * 255]
+}

package/src/colors/palette-to-hex/palette-to-hex.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test, vi } from 'vitest'
+import { CARTO_PALETTES } from '../carto-palettes/carto-palettes'
+import { paletteToHex } from './palette-to-hex'
+
+const SUNSET = [
+  '#f3e79b',
+  '#fac484',
+  '#f8a07e',
+  '#eb7f86',
+  '#ce6693',
+  '#a059a0',
+  '#5c53a5',
+]
+
+describe('paletteToHex', () => {
+  test('returns the palette ramp in order', () => {
+    expect(paletteToHex('Sunset')).toEqual(SUNSET)
+  })
+
+  test('resolves the name case-insensitively', () => {
+    expect(paletteToHex('sunset')).toEqual(SUNSET)
+    expect(paletteToHex('SUNSET')).toEqual(SUNSET)
+    expect(paletteToHex('sUnSeT')).toEqual(SUNSET)
+  })
+
+  test('returns the full ramp for a qualitative palette', () => {
+    // Bold carries 12 categorical colors, longer than the seq/div 7.
+    expect(paletteToHex('Bold')).toHaveLength(12)
+    expect(paletteToHex('Bold')).toEqual([...CARTO_PALETTES.Bold])
+  })
+
+  test('returns undefined and warns for an unknown palette', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    expect(paletteToHex('nope')).toBeUndefined()
+    expect(warn).toHaveBeenLastCalledWith('paletteToHex: nope unknown palette')
+    warn.mockRestore()
+  })
+
+  test('does not resolve inherited object keys', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    for (const key of ['__proto__', 'constructor', 'toString']) {
+      expect(paletteToHex(key)).toBeUndefined()
+    }
+    warn.mockRestore()
+  })
+
+  test('returns a fresh copy that does not mutate the shared map', () => {
+    const ramp = paletteToHex('Sunset')!
+    ramp[0] = '#000000'
+    ramp.reverse()
+    expect(CARTO_PALETTES.Sunset).toEqual(SUNSET)
+  })
+
+  test('has no case-insensitive name collisions', () => {
+    const lowered = new Set(
+      Object.keys(CARTO_PALETTES).map((n) => n.toLowerCase()),
+    )
+    expect(lowered.size).toBe(Object.keys(CARTO_PALETTES).length)
+  })
+})

package/src/colors/palette-to-hex/palette-to-hex.ts

@@ -0,0 +1,45 @@
+import {
+  CARTO_PALETTES,
+  type PaletteName,
+} from '../carto-palettes/carto-palettes'
+
+/** Lowercased name → ramp, for case-insensitive resolution. */
+const PALETTES_BY_LOWER = new Map<string, readonly string[]>(
+  Object.entries(CARTO_PALETTES).map(([name, colors]) => [
+    name.toLowerCase(),
+    colors,
+  ]),
+)
+
+/**
+ * Resolves a CARTOColors palette name to its hex ramp.
+ *
+ * Matching is case-insensitive (`'sunset'` resolves `'Sunset'`). Returns the
+ * palette's largest class-count ramp. To get RGBA tuples, compose with
+ * `hexToRgba`: `paletteToHex('Sunset')?.map((hex) => hexToRgba(hex))`.
+ *
+ * @param name - CARTOColors palette name (e.g. `'Sunset'`), any casing.
+ * @returns A fresh `string[]` of hex stops (a copy — safe to mutate), or
+ *   `undefined` for an unknown palette.
+ *
+ * @example
+ * ```ts
+ * paletteToHex('Sunset') // ['#f3e79b', …, '#5c53a5']
+ * paletteToHex('sunset') // ['#f3e79b', …, '#5c53a5']
+ * ```
+ */
+export function paletteToHex(
+  // `PaletteName | (string & {})` keeps autocomplete for known names while
+  // still accepting arbitrary casing (which isn't a `PaletteName` literal).
+  name: PaletteName | (string & {}),
+): string[] | undefined {
+  // Static snapshot of cartocolor's max class-count ramp per palette; if
+  // per-class-count ramps are ever needed, source them from `cartocolor`.
+  const hexes = PALETTES_BY_LOWER.get(name.toLowerCase())
+  if (!hexes) {
+    // eslint-disable-next-line no-console
+    console.warn(`paletteToHex: ${name} unknown palette`)
+    return
+  }
+  return hexes.slice()
+}

package/src/colors/rgba-to-hex/rgba-to-hex.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test, vi } from 'vitest'
+import { rgbaToHex } from './rgba-to-hex'
+
+describe.each([
+  { rgba: [0, 0, 0, 255], expected: '#000000ff' },
+  { rgba: [255, 255, 255, 0], expected: '#ffffff00' },
+  { rgba: [255, 255, 255, 127], expected: '#ffffff7f' },
+  { rgba: [255, 255, 255], options: { withPrefix: false }, expected: 'ffffff' },
+])('rgbaToHex(%s, %i)', ({ rgba, options, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(rgbaToHex(rgba, options)).toEqual(expected)
+  })
+})
+
+describe.each([
+  {
+    rgba: undefined,
+    error: 'rgbaToHex: invalid array or empty values',
+  },
+  {
+    rgba: [],
+    error: 'rgbaToHex: invalid array or empty values',
+  },
+  {
+    rgba: [0, -1, 0],
+    error: 'rgbaToHex: [0,-1,0] invalid array value format',
+  },
+])('rgbaToHex fails', ({ rgba, error }) => {
+  test(`returns ${error}`, () => {
+    const err = vi.spyOn(console, 'warn').mockImplementation(() => vi.fn())
+    expect(rgbaToHex(rgba)).toBeUndefined()
+    expect(err).toHaveBeenLastCalledWith(error)
+  })
+})

package/src/colors/rgba-to-hex/rgba-to-hex.ts

@@ -0,0 +1,42 @@
+import type { RgbaToHexOptions } from './types'
+
+/**
+ * Converts an RGBA color array to a hexadecimal string, ideal for converting deck.gl colors to CSS-compatible format.
+ *
+ * @param rgba - Array of RGBA values (each 0-255). Accepts `[r, g, b]` or `[r, g, b, a]`.
+ * @param options - Options including `withPrefix` to control `#` prefix (default: `true`).
+ * @returns The hex color string, or `undefined` for invalid inputs.
+ *
+ * @example
+ * ```ts
+ * rgbaToHex([255, 0, 0])              // '#ff0000'
+ * rgbaToHex([255, 0, 0, 128])         // '#ff000080'
+ * rgbaToHex([0, 255, 0], { withPrefix: false }) // '00ff00'
+ * ```
+ */
+export function rgbaToHex(
+  rgba: number[] | undefined,
+  { withPrefix = true }: RgbaToHexOptions = {},
+): string | undefined {
+  if (!rgba?.length) {
+    // eslint-disable-next-line no-console
+    console.warn(`rgbaToHex: invalid array or empty values`)
+    return
+  }
+
+  const hasInvalidValue = rgba.some((value) => value < 0 || value > 255)
+  if (hasInvalidValue) {
+    // eslint-disable-next-line no-console
+    console.warn(`rgbaToHex: [${rgba.toString()}] invalid array value format`)
+    return
+  }
+
+  const hexadecimal = rgba
+    .map((value) => {
+      const hex = value.toString(16)
+      return hex.padStart(2, '0')
+    })
+    .join('')
+
+  return `${withPrefix ? '#' : ''}${hexadecimal}`
+}

package/src/colors/rgba-to-hex/types.ts

@@ -0,0 +1,9 @@
+/**
+ * `RgbaToHexOptions` is an object with an optional property `withPrefix` of type
+ * `boolean`.
+ * @property {boolean} withPrefix - boolean - Whether to include the '#' prefix in the hex
+ * string.
+ */
+export interface RgbaToHexOptions {
+  withPrefix?: boolean
+}