@carto/ps-utils 2.0.1 → 2.1.0

package/dist/types/clipboard/copy.d.ts

@@ -1,14 +1,12 @@
 /**
- * This function is a helper function to copy text to the clipboard.
- *
- * @param {string} text - The text to copy to the clipboard.
- *
- * @returns {void}
+ * Asynchronously copies text content to the user's clipboard using the Clipboard API.
  *
+ * @param text - The text content to copy to the clipboard.
+ * @returns A promise that resolves when the text is successfully copied, or rejects with an error.
  *
  * @example
  * ```ts
- * copy('Hello world!')
+ * await copy('Hello world!')
  * ```
  */
 export declare function copy(text: string): Promise<void>;

package/dist/types/colors/carto-palettes/carto-palettes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare const CARTO_PALETTES: {
+    ag_GrnYl: string[];
+    ag_Sunset: string[];
+    BluGrn: string[];
+    BluYl: string[];
+    BrwnYl: string[];
+    Burg: string[];
+    BurgYl: string[];
+    DarkMint: string[];
+    Emrld: string[];
+    Magenta: string[];
+    Mint: string[];
+    OrYel: string[];
+    Peach: string[];
+    PinkYl: string[];
+    Purp: string[];
+    PurpOr: string[];
+    RedOr: string[];
+    Sunset: string[];
+    SunsetDark: string[];
+    Teal: string[];
+    TealGrn: string[];
+    ArmyRose: string[];
+    Earth: string[];
+    Fall: string[];
+    Geyser: string[];
+    TealRose: string[];
+    Temps: string[];
+    Tropic: string[];
+    Antique: string[];
+    Bold: string[];
+    Pastel: string[];
+    Prism: string[];
+    Safe: string[];
+    Vivid: string[];
+};
+/** A known CARTOColors palette name. */
+export type PaletteName = keyof typeof CARTO_PALETTES;

package/dist/types/colors/hex-to-rgba/hex-to-rgba.d.ts

@@ -1,24 +1,15 @@
 /**
- * It converts a hexadecimal color to an array of numbers
+ * Converts a hexadecimal color string to an RGBA array, useful for deck.gl layer styling and canvas operations.
  *
- * @param {string} hexadecimal - hexadecimal string, including # or not
- * @param {number} alpha - opacity of final color, value must be between 0-1
- *
- * @returns An array of numbers.
+ * @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
- *
- * 6 digits hexadecimal:
- * ```ts
- * hexToRgba('#d1d1d1', 1)
- * ```
- * 3 digits hexadecimal:
- * ```ts
- * hexToRgba('#d1d', 1)
- * ```
- * 2 digits hexadecimal:
  * ```ts
- * hexToRgba('#d1', 1)
+ * hexToRgba('#ff0000', 0.8) // [255, 0, 0, 204]
+ * hexToRgba('#f00', 0.5)    // [255, 0, 0, 127.5]
+ * hexToRgba('00ff00')       // [0, 255, 0, 255]
  * ```
  */
 export declare function hexToRgba(hexadecimal: string, alpha?: number): [number, number, number, number] | undefined;

package/dist/types/colors/palette-to-hex/palette-to-hex.d.ts

@@ -0,0 +1,19 @@
+import { PaletteName } from '../carto-palettes/carto-palettes';
+/**
+ * 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 declare function paletteToHex(name: PaletteName | (string & {})): string[] | undefined;

package/dist/types/colors/palette-to-hex/palette-to-hex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/colors/rgba-to-hex/rgba-to-hex.d.ts

@@ -1,28 +1,16 @@
 import { RgbaToHexOptions } from './types';
 /**
- * It converts an array of RGBA values to a hexadecimal string.
+ * Converts an RGBA color array to a hexadecimal string, ideal for converting deck.gl colors to CSS-compatible format.
  *
- * @param {number[]} rgba - rgba array, including alpha or not
- * @param {RgbaToHexOptions} options - options to parse
- *
- * @returns A string
+ * @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
- *
- * Without alpha value:
- * ```ts
- * rgbaDeckGLToHex([0, 0, 0]) // => '#000000'
- * ```
- *
- * With alpha value:
  * ```ts
- * rgbaDeckGLToHex([0, 0, 0, 1]) // => '#000000FF'
+ * rgbaToHex([255, 0, 0])              // '#ff0000'
+ * rgbaToHex([255, 0, 0, 128])         // '#ff000080'
+ * rgbaToHex([0, 255, 0], { withPrefix: false }) // '00ff00'
  * ```
- *
- * Without prefix:
- * ```ts
- * rgbaDeckGLToHex([0, 0, 0], { withPrefix: false }) // => '000000'
- * ```
- *
  */
 export declare function rgbaToHex(rgba: number[] | undefined, { withPrefix }?: RgbaToHexOptions): string | undefined;

package/dist/types/debounce/debounce.d.ts

@@ -1,7 +1,17 @@
 /**
- * Returns a debounced version of the provided function.
+ * Creates a debounced version of a function that delays execution until after the specified wait time has elapsed since the last invocation.
+ *
  * @param func - The function to debounce.
- * @param {number} waitFor - The number of milliseconds to wait before invoking the debounced function.
+ * @param waitFor - The delay in milliseconds to wait before executing.
  * @returns A debounced version of the provided function.
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce((query: string) => {
+ *   fetchResults(query)
+ * }, 300)
+ *
+ * debouncedSearch('hello') // Only executes after 300ms of inactivity
+ * ```
  */
 export declare function debounce<F extends (...args: unknown[]) => unknown>(func: F, waitFor: number): (...args: Parameters<F>) => ReturnType<F>;

package/dist/types/formatters/constants.d.ts

@@ -1 +1,23 @@
-export declare const DEFAULT_FORMATTERS_CONFIG: Record<string, Intl.NumberFormatOptions | Intl.DateTimeFormatOptions>;
+/**
+ * Default configuration options for the formatter utilities (`formatNumber`, `formatCurrency`, `formatDate`).
+ *
+ * @remarks
+ * Contains preset `Intl.NumberFormatOptions` and `Intl.DateTimeFormatOptions` for three keys:
+ * - `NUMBER` - Compact decimal notation with 1 fraction digit.
+ * - `CURRENCY` - Compact USD currency with 2 fraction digits.
+ * - `DATE` - Numeric year, 2-digit month and day.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_FORMATTERS_CONFIG } from '@carto/ps-utils'
+ *
+ * // Override defaults for a custom number format
+ * const options = { ...DEFAULT_FORMATTERS_CONFIG.NUMBER, maximumFractionDigits: 3 }
+ * ```
+ */
+export type DefaultFormatterKey = 'NUMBER' | 'CURRENCY' | 'DATE';
+export declare const DEFAULT_FORMATTERS_CONFIG: Record<string, Intl.NumberFormatOptions | Intl.DateTimeFormatOptions> & {
+    NUMBER: Intl.NumberFormatOptions;
+    CURRENCY: Intl.NumberFormatOptions;
+    DATE: Intl.DateTimeFormatOptions;
+};

package/dist/types/formatters/date/format-date.d.ts

@@ -1,12 +1,17 @@
 /**
- * Formats a Date or number to a string based on the given options.
- * This function could be used to format a Date, in Date format or miliseconds, in specific locale and options.
- * @public
+ * Formats a date or timestamp according to locale-specific conventions using the `Intl.DateTimeFormat` API.
  *
- * @export
- * @param {number | Date} value
- * @param {string | string[]} locales
- * @param {Intl.DateTimeFormatOptions} [options]
- * @return {string}
+ * @param value - The date to format (Date object or timestamp in milliseconds).
+ * @param locales - Locale identifier(s) for formatting (e.g., `'en-US'`, `'fr-FR'`).
+ * @param options - Date/time formatting options to override the defaults (numeric year, 2-digit month and day).
+ *   When `dateStyle` or `timeStyle` is provided the defaults are not applied, as they are incompatible with
+ *   individual date/time component options.
+ * @returns The formatted date string.
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date('2024-03-15'), 'en-US') // "03/15/2024"
+ * formatDate(new Date('2024-03-15'), 'en-US', { month: 'long' }) // "March 15, 2024"
+ * ```
  */
 export declare function formatDate(value: number | Date, locales: string | string[], options?: Intl.DateTimeFormatOptions): string;

package/dist/types/formatters/number/format-number.d.ts

@@ -1,34 +1,31 @@
 /**
- * Formats a number to a string.
- * @public
+ * Formats a number with locale-aware separators, compact notation, and customizable precision.
  *
- * @example
+ * @param value - The number to format.
+ * @param locale - The locale identifier (e.g., `'en-US'`, `'es-ES'`).
+ * @param options - `Intl.NumberFormatOptions` to override the defaults (compact decimal with 1 fraction digit).
+ * @returns The formatted number string.
  *
+ * @example
  * ```ts
- * formatNumber(3001, 'es-ES') // => '3 mil'
+ * formatNumber(123456, 'en-US')    // "123.5K"
+ * formatNumber(1234567, 'en-US')   // "1.2M"
+ * formatNumber(123456, 'es-ES')    // "123 mil"
  * ```
- *
- * @export
- * @param {number} value - The number to be formatted.
- * @param {string} locale - The locale to be used.
- * @param {Intl.NumberFormatOptions} [options] - The options to be used.
- * @return {string}
  */
 export declare function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
 /**
- * Formats a number to a currency string.
- * @public
+ * Formats a number as a currency value with proper symbols and regional conventions.
  *
- * @example
+ * @param value - The monetary value to format.
+ * @param locale - The locale identifier (e.g., `'en-US'`, `'fr-FR'`).
+ * @param options - `Intl.NumberFormatOptions` to override the defaults (compact USD with 2 fraction digits).
+ * @returns The formatted currency string.
  *
+ * @example
  * ```ts
- * formatCurrency(3001, 'en-US') // => '$3.00K'
+ * formatCurrency(123456, 'en-US')                          // "$123.46K"
+ * formatCurrency(123456, 'fr-FR', { currency: 'EUR' })     // "123,46 k €"
  * ```
- *
- * @export
- * @param {number} value - The number to be formatted.
- * @param {string} locale - The locale to be used.
- * @param {Intl.NumberFormatOptions} [options] - The options to be used.
- * @return {string}
  */
 export declare function formatCurrency(value: number, locale: string, options?: Intl.NumberFormatOptions): string;

package/dist/types/index.d.ts

@@ -1,5 +1,8 @@
 export { copy } from './clipboard/copy';
+export { CARTO_PALETTES } from './colors/carto-palettes/carto-palettes';
+export type { PaletteName } from './colors/carto-palettes/carto-palettes';
 export { hexToRgba } from './colors/hex-to-rgba/hex-to-rgba';
+export { paletteToHex } from './colors/palette-to-hex/palette-to-hex';
 export { rgbaToHex } from './colors/rgba-to-hex/rgba-to-hex';
 export { debounce } from './debounce/debounce';
 export { DEFAULT_FORMATTERS_CONFIG } from './formatters/constants';

package/dist/types/strings/match-text/match-text.d.ts

@@ -1,12 +1,16 @@
 import { MatchTextOptions } from './types';
 /**
- * It takes a string, an array of strings, and an optional object of options, and returns an
- * array of strings that match the input string
- * @param {string | RegExp} text - The text to match against.
- * @param {T[] | string} data - The data to match against.
- * @param {MatchTextOptions} options - The options to use.
+ * Performs intelligent text matching with optional Unicode normalization and custom matching functions.
  *
- * @returns {T[] | string | null} - The matched data or null.
+ * @param value - The text or RegExp pattern to match against.
+ * @param data - The data to search (array of items or a single string).
+ * @param options - Optional configuration for custom match function and normalization.
+ * @returns Matched items from an array, the original string if it matches, or `null`.
  *
+ * @example
+ * ```ts
+ * matchText('york', ['New York', 'Los Angeles']) // ['New York']
+ * matchText('barce', locations, { matchFn: (item) => item.name })
+ * ```
  */
 export declare function matchText<T>(value: string | RegExp, data: T[] | string, { matchFn, normalizeOptions }?: MatchTextOptions<T>): T[] | string | null;

package/dist/types/strings/normalize/normalize.d.ts

@@ -1,18 +1,15 @@
 import { NormalizeOptions } from './types';
 /**
- * It takes a string and returns a string normalized.
- * @param {string} data - The data to be normalized.
- * @param {NormalizeOptions} options  - data - The string to be normalized.
- * @returns A string
+ * Normalizes a Unicode string by removing diacritics and special characters for consistent text comparison.
  *
- * @remarks
- * The normalization by default is NFD
+ * @param data - The string to normalize.
+ * @param options - Normalization options including Unicode form and replacement pattern.
+ * @returns The normalized string with diacritics removed.
  *
  * @example
- *
  * ```ts
- * normalize('foo bar')
+ * normalize('café')       // 'cafe'
+ * normalize('São Paulo')  // 'Sao Paulo'
  * ```
- *
  */
 export declare function normalize(data: string, { format, replaceUnicode }?: NormalizeOptions): string;

package/dist/types/strings/routes/replace-route.d.ts

@@ -1,23 +1,19 @@
 import { Route, Values } from './types';
 /**
- * Replace route with values from array or object.
- * @param {Route} data
- * @param {Values} values
+ * Dynamically replaces route parameters (`:paramName`) with values from an object or array.
  *
- * @returns {Route}
- *
- * @example
- * ```ts
- * replaceRoute('/user/:id', { id: 1 }) // /user/1
- * replaceRoute('/user/:id/:name', [1, 'John']) // /user/1/John
- * ```
+ * @param data - The route template string containing `:paramName` placeholders.
+ * @param values - An object or array of values to substitute into the route.
+ * @returns The route string with parameters replaced.
  *
  * @remarks
- * This function is used to replace the route with the values from the array or object. If the values are not found, it will replace it with `undefined`.
+ * Missing values are replaced with an empty string.
  *
+ * @example
  * ```ts
- *  replaceRoute('/user/:id/:name', [1]) // /user/1/undefined
+ * replaceRoute('/user/:id', { id: '123' })         // '/user/123'
+ * replaceRoute('/tiles/:z/:x/:y', { z: 10, x: 512, y: 256 }) // '/tiles/10/512/256'
+ * replaceRoute('/user/:id/:name', ['123', 'john'])  // '/user/123/john'
  * ```
- *
- **/
+ */
 export declare function replaceRoute(data: Route, values?: Values): Route;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-utils",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "CARTO's Professional Service Helpers library",
   "type": "module",
   "dependencies": {},
@@ -19,10 +19,14 @@
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "files": [
+      "dist"
+    ]
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "keywords": [
     "carto",

package/src/clipboard/copy.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { copy } from './copy'
+
+describe('utils :: clipboard :: copy', () => {
+  beforeEach(() => {
+    let clipboardData = ''
+    const mockClipboard = {
+      clipboard: {
+        writeText: vi.fn((data: string) => {
+          clipboardData = data
+        }),
+        readText: vi.fn(() => {
+          return clipboardData
+        }),
+      },
+    }
+
+    Object.assign(navigator, 'clipboard', {
+      ...mockClipboard,
+    })
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  /**
+   * @jest-environment jsdom
+   */
+  test('should copy text to clipboard', async () => {
+    const data = 'test'
+
+    try {
+      await copy(data)
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error(error)
+    }
+
+    expect(navigator.clipboard.readText()).toBe(data)
+  })
+
+  test('should throw an error if clipboard not defined', async () => {
+    Object.defineProperty(navigator, 'clipboard', { value: null })
+    const string = 'test'
+
+    await expect(() => copy(string)).rejects.toThrowError()
+  })
+})

package/src/clipboard/copy.ts

@@ -0,0 +1,18 @@
+/**
+ * Asynchronously copies text content to the user's clipboard using the Clipboard API.
+ *
+ * @param text - The text content to copy to the clipboard.
+ * @returns A promise that resolves when the text is successfully copied, or rejects with an error.
+ *
+ * @example
+ * ```ts
+ * await copy('Hello world!')
+ * ```
+ */
+export async function copy(text: string): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text)
+  } catch (e: unknown) {
+    throw new Error(e as string) // copy failed.
+  }
+}