color-shorthand-hex-to-six-digit

Convert shorthand hex color codes into full

Table of Contents

• Install
• Purpose
• Examples
• Usage in Gulp environment
• API
• Reliability
• Contributing
• Licence

Install

npm i color-shorthand-hex-to-six-digit

// consume as CommonJS require():
const conv = require("color-shorthand-hex-to-six-digit");
// or as an ES Module:
import conv from "color-shorthand-hex-to-six-digit";

Here's what you'll get:

⬆ back to top

Purpose

Email newsletters use a lot of styling using HTML attributes, for example, <td bgcolor='#cccccc'>. As you know, there is alternative way to write color codes in HEX — shorthand, for example, <td bgcolor='#ccc'>.

Certain contemporary email consumption software doesn't accept shorthand hex colour codes, what means you have to ensure all your email templates use only full-length colour codes. Some tooling libraries that work with SASS shorten the colour hex codes, and that's a best practice for web development, but not for email. We need a tool/library which could convert any shorthand hex codes from any input (array, plain object or string) into full notation.

This library takes any input: array (of strings, plain objects, other arrays or nested combination thereof), plain object (containing anything in values, including nested plain objects, arrays or strings) or string. Once received, it traverses the input and converts all found shorthand hex colour codes (#abc) into full-length (#aabbcc).

Additionally, all letters in all hex codes are converted to lowercase.

⬆ back to top

Examples

const conv = require("color-shorthand-hex-to-six-digit");

// converts shorthand hex color codes within strings:
conv("aaaa #f0c zzzz\n\t\t\t#fc0");
// => 'aaaa #ff00cc zzzz\n\t\t\t#ffcc00'

// converts shorthand hex colour codes within plain objects:
conv({
  a: "#ffcc00",
  b: "#f0c",
  c: "text"
});
// => {
//   a: '#ffcc00',
//   b: '#ff00cc',
//   c: 'text'
// }

// converts shorthand hex colour codes within arrays:
conv(["#fc0", "#f0c", "text", ""]);
// => [
//   '#ffcc00', '#ff00cc', 'text', ''
// ]

// converts shorthand hex colour codes within nested spaghetti's:
conv([[[[[[{ x: ["#fc0"] }]]]]], { z: "#f0c" }, ["text"], { y: "" }]);
// => [
//   [[[[[{x: ['#ffcc00']}]]]]], {z: '#ff00cc'}, ['text'], {y: ''}
// ]

// in all other cases it silently returns the input:
conv(null);
// => null

⬆ back to top

Usage in Gulp environment

You don't need a Gulp plugin; you can simply use this library whenever you get in control of the final stream, or especially, SCSS variables.

For example, tap the color-shorthand-hex-to-six-digit right after importing the SCSS variables. I hope you are not misbehaving and all your colour variables are in one place only, as variables.

// import SCSS variables from file (modules/src/scss/_variables.scss)

// native Node function to help with paths:
const path = require("path");
// convert variables SCSS file to .JSON:
const scssToJson = require("scss-to-json");
// lodash:
const _ = require("lodash");
// ...

function getScssVars() {
  var sassFilePath = path.resolve(
    __dirname,
    "modules/src/scss/_variables.scss"
  );
  var tempSassVars = scssToJson(sassFilePath);
  sassVars = _.mapKeys(tempSassVars, function(value, key) {
    return key.slice(1);
  });
  // convert all bad hex codes:
  sassVars = convShorthand(sassVars);
  // console.log('sassVars = ' + JSON.stringify(sassVars, null, 4))
}

I coded the color-shorthand-hex-to-six-digit to be recursive, that is, you can pass any nested objects/arrays/strings, no matter how deep-nested or tangled - all 3-character hex codes will be converted within the input.

If there is nothing to fix, color-shorthand-hex-to-six-digit behaves well, returning whatever was given, so feel free to assign your sources to the output of color-shorthand-hex-to-six-digit.

⬆ back to top

API

The one and only input argument can be anything: string, plain object, nested array of whatever; you name it. If input is not workable, for example, it's a function; it's simply returned intact. This way, this library acts like a safety valve that acts when wrong hex codes pass through it, converting them.

PS. Input argument (in case of plain objects and arrays) is not mutated in any way. This package will clone the input and work on its copy. This is important. No teenage turtle mutations here.

⬆ back to top

Reliability

I'm using only the best ingredients, namely hex-color-regex by @tunnckocore and standalone Lodash functions (_.clonedeep, _.isplainobject and _.isstring). This library is being currently used in commercial projects.

⬆ back to top

Contributing

• If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.

• If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)

Copyright © 2018 Codsen Ltd, Roy Revelt