@datawrapper/shared-darkmode-no-invert v0.44.0

@datawrapper/shared

a set of shared methods that can be used throughout Datawrapper

Import single functions:

import purifyHtml from '@datawrapper/shared/purifyHtml';

Import entire package:

import shared from '@datawrapper/shared';
shared.purifyHtml();
shared.httpReq();

API reference

• __(key, scope) ⇒ string
• area(vertices) ⇒ number
• arrayToObject(o) ⇒ object
• autoTickFormat(column) ⇒ string
• autoTickFormatDate(range, precision) ⇒ string
• autoTickFormatNumber(range) ⇒ string
• clone(object) ⇒ *
• colorLightness(hexColor) ⇒ number
• columnFormatter(numeral, column, metadata, axis) ⇒ function
• columnNameToVariable(name) ⇒ string
• combinations(input) ⇒ Array.<array>
• dateColumnFormatter(column) ⇒ function
• decodeHtml(input) ⇒ string
• defaultColors(theme) ⇒ *
• defaultOverlayTitle(vis, colName) ⇒ string
• deleteJSON(url, callback) ⇒ Promise
• drawPattern(parameters)
• equalish(a, b) ⇒ boolean
• escapeHtml(unsafe) ⇒ string
• estimateTextWidth(text, fontSize) ⇒ number
• fetchJSON(url, method, credentials, body, callback) ⇒ Promise
• formatNumber(numeral, value, options) ⇒ string
• get(object, key, _default) ⇒
• getJSON(url, credentials, callback) ⇒ Promise
• highlightTimer(action, delay) ⇒ object
• httpReq(path, options) ⇒ Promise
  • .delete()
  • .get()
  • .head()
  • .patch()
  • .post()
  • .put()
• isValidUrl(input) ⇒ boolean
• kMeans(values, numCluster) ⇒ array.<Array.<number>>
• loadScript(src, callback)
• loadStylesheet(src, callback)
• normalizeAlphaNumKey(key) ⇒ string
• normalizeNumKey(key) ⇒ number
• numberColumnFormatter(numeral, config) ⇒ function
• observeFonts(fontsJSON, typographyJSON) ⇒ Promise
• opts : object
• patchJSON(url, body, callback) ⇒ Promise
• postEvent(chartId) ⇒ function
• postJSON(url, body, callback) ⇒ Promise
• purifyHTML(input, allowed) ⇒ string
• putJSON(url, body, callback) ⇒ Promise
• round(value, decimals) ⇒ number
• set(object, key, value) ⇒
• significantDimension(values, tolerance) ⇒ number
• smartRound(values, addPrecision, tolerance) ⇒
• tailLength(value) ⇒ number
• toFixed(value) ⇒ string
• trackEvent(category, category, category, category)
• trackPageView(loadTime)
• truncate(str, start, end) ⇒ string

__(key, scope) ⇒ string

translates a message key. translations are originally stored in a Google spreadsheet that we're pulling into Datawrapper using the scripts/update-translations script, which stores them as :locale.json files in the /locale folders (both in core as well as inside plugin folders)

for the client-side translation to work we are also storing the translations in the global window.dw.backend.__messages object. plugins that need client-side translations must set "svelte": true in their plugin.json

Returns: string - -- the translated text

area(vertices) ⇒ number

Computes the area of a polygon

Returns: number - -- polygon area, might be negative

arrayToObject(o) ⇒ object

This function fixes an uglyness when working with PHP backends. in PHP, there is no distiction between arrays and objects, so PHP converts an empty object {} to a empty array []. When this empty array then ends up in client-side JS functions which might start to assign values to the array using arr.foo = "bar" which results in a data structure like this:

Example

console.log(arr);
[]
  foo: "bar"
  length: 0
  <prototype>: Array []

console.log(arrayToObject(arr));
Object { foo: "bar" }

autoTickFormat(column) ⇒ string

Convenient wrapper around autoTickFormatNumber and autoTickFormatDate. Returns either a numeral.js or day.js format, depending on the column type.

Returns: string - -- a numeral|dayjs format string

autoTickFormatDate(range, precision) ⇒ string

auto-detects a nice default axis tick format for date columns based on the input range and precision

Returns: string - - day.js compatible format string

Example

import {autoTickFormatDate} from '@datawrapper/shared/autoTickFormat';
autoTickFormatDate([new Date(2000,0,1), new Date(2002,0,1)], 'quarter'); // 'YYYY|[Q]Q'

autoTickFormatNumber(range) ⇒ string

auto-detects a nice default axis tick format for numeric columns based on the input range

Returns: string - - numeral.js compatible format string

Example

import {autoTickFormatNumber} from '@datawrapper/shared/autoTickFormat';
autoTickFormatNumber([0,100]); // '0,0.[00]'
autoTickFormatNumber([0.2,0.7]); // '0,0.00[00]'

clone(object) ⇒ *

Clones an object

Returns: * - - the cloned thing

colorLightness(hexColor) ⇒ number

Returns the Lab lightness value of a given hexidecimal RGB color. Uses chroma-js to convert from Hex to Lab, but only adds a few hundreds bytes to your build.

To use this function, you have to manually install chroma-js using npm install chroma-js.

Returns: number - - the Lab lightness, between 0 (black) and 100 (white)

Example

import colorLightness from '@datawrapper/shared/colorLightness';
colorLightness('#ff3399') // 57.9

columnFormatter(numeral, column, metadata, axis) ⇒ function

This function returns a formatting function based, given a column object, a metadata object and the axis column name.

columnNameToVariable(name) ⇒ string

converts a column name to a variable name that can be used in the custom column editor. variable names can't contain spaces and special characters and are also converted to lowercase.

Returns: string - -- variable name

Example

import columnNameToVariable from '@datawrapper/shared/columnNameToVariable';

columnNameToVariable('GDP (per cap.)') // gdp_per_cap

combinations(input) ⇒ Array.<array>

computes all combinations of input elements

Returns: Array.<array> - -- array of combinations

Example

// returns [['a','b'], ['a'], ['b']]
combinations(['a', 'b']);

Example

// returns [[1,2,3], [1,2], [1,3], [1], [2,3], [2], [3]]
combinations([1,2,3])

dateColumnFormatter(column) ⇒ function

This function returns a date formatting function based on a dw column object. The implementation is backwards-compatible with our old Globalize-based date formatting, but uses dayjs under the hood.

decodeHtml(input) ⇒ string

Removes all html tags and decodes html entities like  

defaultColors(theme) ⇒ *

defines colors for the various chart elements like axis text, gridlines, bar background etc. based on the theme background color, and some other optional theme parameters

Returns: * - -- object with color definitions

Example

// returns {"tickText":{"secondary":"#9d9d9d","primary":"#d9d9d9"},"series":"#f1f1f1","value":"#d9d9d9","axis":"#f1f1f1","gridline":"#707070","fallbackBaseColor":"#f1f1f1"}
defaultColors({"colors": {"background": "#333333"}});

Example

// returns {"tickText":{"secondary":"#ffffff","primary":"#ffffff"},"series":"#ffffff","value":"#fef2e4","axis":"#ffffff","gridline":"#fedeb5","fallbackBaseColor":"#ffffff"}
defaultColors({"colors": {"bgBlendRatios": {"gridline": 0.5,"tickText": {"primary": 0,"secondary": 0}},"chartContentBaseColor": "#ffffff","background": "#FCB716"}});

defaultOverlayTitle(vis, colName) ⇒ string

returns the overlays column title

deleteJSON(url, callback) ⇒ Promise

Deprecated

Download and parse a remote JSON endpoint via DELETE. credentials are included automatically Use httpReq or delete instead.

Example

import { deleteJSON } from '@datawrapper/shared/fetch';

deleteJSON('http://api.example.org/chart/123').then(() => {
    console.log('deleted!')
});

drawPattern(parameters)

draws a configurable pattern into an svg pattern def, so that it can be used as a fill

equalish(a, b) ⇒ boolean

returns true if two numeric values are close enough

Example

// returns true
equalish(0.333333, 1/3)

Example

// returns false
equalish(0.333, 1/3)

escapeHtml(unsafe) ⇒ string

returns escaped HTML that can be used to display untrusted content

estimateTextWidth(text, fontSize) ⇒ number

returns the estimated width of a given text in Roboto. this method has proven to be a good compromise between pixel-perfect but expensive text measuring methods using canvas or getClientBoundingRect and just multiplying the number of characters with a fixed width.

be warned that this is just a rough estimate of the text width. the character widths will vary from typeface to typeface and may be off quite a bit for some fonts (like monospace fonts).

Example

import estimateTextWidth from '@datawrapper/shared/estimateTextWidth';
// or import {estimateTextWidth} from '@datawrapper/shared';
const width = estimateTextWidth('my text', 12);

fetchJSON(url, method, credentials, body, callback) ⇒ Promise

Deprecated

Download and parse a remote JSON document. Use httpReq instead

Example

import { fetchJSON } from '@datawrapper/shared/fetch';
fetchJSON('http://api.example.org', 'GET', 'include');

formatNumber(numeral, value, options) ⇒ string

special number formatting that can deal with microtypography and "prepend currencies" (e.g., −$1234.57)

Returns: string - - the formatted number

Example

// returns '1234.57'
formatNumber(numeral, 1234.567)

Example

// returns '−$1234.57'
formatNumber(numeral, -1234.567, { prepend: '$' })

get(object, key, _default) ⇒

Safely access object properties without throwing nasty cannot access X of undefined errors if a property along the way doesn't exist.

Returns: the value

Example

import get from '@datawrapper/shared/get';
const someObject = { key: { list: ['a', 'b', 'c']}};
get(someObject, 'key.list[2]') // returns 'c'
get(someObject, 'missing.key') // returns undefined
get(someObject, 'missing.key', false) // returns false

getJSON(url, credentials, callback) ⇒ Promise

Deprecated

Download and parse a JSON document via GET. Use httpReq or get instead.

Example

import { getJSON } from '@datawrapper/shared/fetch';
// use it callback style
getJSON('http://api.example.org', 'include', function(data) {
    console.log(data);
});
// or promise-style
getJSON('http://api.example.org')
  .then(data => {
     console.log(data);
  });

highlightTimer(action, delay) ⇒ object

A delayed highlight setter

Example

import {highlightTimer} from '@datawrapper/shared';
const myTimer = highlightTimer(value => {
    if (value) {
        selection.style('opacity', d => d === value ? 1 : 0.3);
    } else {
        selection.style('opacity', 1);
    }
});

lines.on('mouseenter', d => myTimer.set(d));
chart.on('mouseleave', myTimer.clear);

httpReq(path, options) ⇒ Promise

The response body is automatically parsed according to the response content type.

Returns: Promise - promise of parsed response body or raw response

Example

import httpReq from '@datawrapper/shared/httpReq';
 let res = await httpReq('/v3/charts', {
     method: 'post',
     payload: {
         title: 'My new chart'
     }
 });
 import { post } from '@datawrapper/shared/httpReq';
 res = await post('/v3/charts', {
     payload: {
         title: 'My new chart'
     }
 });
 // send raw csv
 await httpReq.put(`/v3/charts/${chartId}/data`, {
      body: csvData,
      headers: {
          'Content-Type': 'text/csv'
      }
  });

• httpReq(path, options) ⇒ Promise
  • .get()
  • .patch()
  • .put()
  • .post()
  • .head()
  • .delete()

httpReq.delete()

Like httpReq but with fixed http method DELETE

See: httpReq

httpReq.get()

Like httpReq but with fixed http method GET

See: httpReq

httpReq.head()

Like httpReq but with fixed http method HEAD

See: httpReq

httpReq.patch()

Like httpReq but with fixed http method PATCH

See: httpReq

httpReq.post()

Like httpReq but with fixed http method POST

See: httpReq

httpReq.put()

Like httpReq but with fixed http method PUT

See: httpReq

isValidUrl(input) ⇒ boolean

checks if a given string is a valid URL

kMeans(values, numCluster) ⇒ array.<Array.<number>>

Performs one-dimensional k-means clustering on an array of numbers. Useful for finding n groups of "similar values".

Returns: array.<Array.<number>> - - array of clusters

Example

import kMeans from '@datawrapper/shared/kMeans';

const values = [1, 1.1, 1.2, 2.1, 3, 3.1, 3.2, 3.3, 7, 7.1, 10];
// returns [[1, 1.1, 1.2, 2.1], [3, 3.1, 3.2, 3.3], [7, 7.1, 10]]
kMeans(values, 3)

loadScript(src, callback)

injects a <script> element to the page to load a new JS script

Example

import { loadScript } from '@datawrapper/shared/fetch';

loadScript('/static/js/library.js', () => {
    console.log('library is loaded');
})

loadStylesheet(src, callback)

injects a <link> element to the page to load a new stylesheet

Example

import { loadStylesheet } from '@datawrapper/shared/fetch';

loadStylesheet('/static/css/library.css', () => {
    console.log('library styles are loaded');
})

normalizeAlphaNumKey(key) ⇒ string

normalize an alphanumerical key for less-strict matching (e.g. in maps)

Returns: string - - normalized key

normalizeNumKey(key) ⇒ number

normalize a numerical key for less-strict matching (e.g. in maps)

Returns: number - - normalized key

numberColumnFormatter(numeral, config) ⇒ function

This function returns a number formatting function based on a column configuration object stored in metadata.data.column-format. The implementation is backwards-compatible with our old Globalize-based number formatting, but uses numeral under the hood.

observeFonts(fontsJSON, typographyJSON) ⇒ Promise

Function that returns a promise, that resolves when all fonts, specified in fontsJSON and typographyJSON have been loaded.

opts : object

Properties

patchJSON(url, body, callback) ⇒ Promise

Deprecated

Example

import { patchJSON } from '@datawrapper/shared/fetch';

patchJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

postEvent(chartId) ⇒ function

Use this function to post event messages out of Datawrapper iframe embeds to the parent website.

Example

import genPostEvent from '@datawrapper/shared/postEvent';
const postEvent = genPostEvent(chart.get('id'));
postEvent('bar:hover', {value: 123});

postJSON(url, body, callback) ⇒ Promise

Deprecated

Download and parse a remote JSON endpoint via POST. credentials are included automatically. Use httpReq or post instead.

Example

import { postJSON } from '@datawrapper/shared/fetch';

postJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

purifyHTML(input, allowed) ⇒ string

Remove all non-whitelisted html tags from the given string

Returns: string - - the cleaned html output

putJSON(url, body, callback) ⇒ Promise

Deprecated

Download and parse a remote JSON endpoint via PUT. credentials are included automatically Use httpReq or put instead.

Example

import { putJSON } from '@datawrapper/shared/fetch';

putJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

round(value, decimals) ⇒ number

rounds a value to a certain number of decimals

Returns: number - - rounded value

Example

import round from '@datawrapper/shared/round';
round(1.2345); // 1
round(1.2345, 2); // 1.23
round(12345, -2); // 12300

set(object, key, value) ⇒

safely set object properties without throwing nasty cannot access X of undefined errors if a property along the way doesn't exist.

Returns: the value

significantDimension(values, tolerance) ⇒ number

computes the significant dimension for a list of numbers That's the number of decimals to which we can round the numbers without loosing information

Returns: number - - number of significant dimensions (= the number of decimals)

Example

import {significantDimension} from '@datawrapper/shared/significantDimension';
significantDimension([0,10,20,30]); // -1

smartRound(values, addPrecision, tolerance) ⇒

rounds an array of numbers to the least number of decimals without loosing any information due to the rounding

Returns: the rounded values

Example

import {smartRound} from '@datawrapper/shared/smartRound';
smartRound([9, 10.5714, 12.1428, 13.7142]); // [9, 11, 12, 14]
smartRound([9, 10.5714, 12.1428, 12.4142]); // [9, 10.6, 12.1, 12.4]

tailLength(value) ⇒ number

returns the length of the "tail" of a number, meaning the number of meaningful decimal places

Example

// returns 3
tailLength(3.123)

Example

// returns 2
tailLength(3.12999999)

toFixed(value) ⇒ string

Automatically converts a numeric value to a string. this is better than the default number to string conversion in JS which sometimes produces ugly strings like "3.999999998"

Example

import toFixed from '@datawrapper/shared/toFixed';
// returns '3.1'
toFixed(3.100001)

trackEvent(category, category, category, category)

tracks a custom event in Matomo

trackPageView(loadTime)

tracks a custom page view in Matomo. Useful for single page apps in Datawrapper, such as the locator maps UI. The page title and URL are automatically detected using the window object.

truncate(str, start, end) ⇒ string

Shorten a string by removing characters from the middle

Example

import truncate from '@datawrapper/shared/truncate';
// returns 'This is a…tring'
truncate('This is a very very long string')