feat(Typescript): Typescript Defs and Flow Improvements (#236)

* feat(Typescript): Typescript Defs and Flow Improvements

* feat(Typescript): Add readableColor to Typescript tests

* fix(Docs): Rebuild docs

.travis.yml

@@ -12,6 +12,9 @@ script:
   - npm test
   - npm run lint
   - npm run flow
+  - npm run build:flow
+  - npm run build:typescript
+  - npm run typescript
 after_success:
   - codecov
   - 'curl -Lo travis_after_all.py https://git.io/travis_after_all'

docs/assets/polished.js

@@ -96,12 +96,12 @@ var endsWith = function (string, suffix) {
  * @example
  * // Styles as object usage
  * const styles = {
- *   '--dimension': stripUnit(100px)
+ *   '--dimension': stripUnit('100px')
  * }
  *
  * // styled-components usage
  * const div = styled.div`
- *   --dimension: ${stripUnit(100px)}
+ *   --dimension: ${stripUnit('100px')}
  * `
  *
  * // CSS in JS Output
@@ -2201,6 +2201,48 @@ var curriedOpacify = /*#__PURE__*/curry(opacify); // eslint-disable-line spaced-
 
 //      
 
+var h = function h(c) {
+  return c / 255 <= 0.03928 ? c / 255 / 12.92 : Math.pow((c / 255 + 0.055) / 1.055, 2.4);
+};
+
+/**
+ * Selects black or white for best contrast depending on the luminosity of the given color.
+ * Follows W3C specs for readability at https://www.w3.org/TR/WCAG20-TECHS/G18.html
+ *
+ * @example
+ * // Styles as object usage
+ * const styles = {
+ *   color: readableColor('#000'),
+ *   color: readableColor('papayawhip'),
+ *   color: readableColor('rgb(255,0,0)'),
+ * }
+ *
+ * // styled-components usage
+ * const div = styled.div`
+ *   color: ${readableColor('#000')};
+ *   color: ${readableColor('papayawhip')};
+ *   color: ${readableColor('rgb(255,0,0)')};
+ * `
+ *
+ * // CSS in JS Output
+ *
+ * element {
+ *   color: "#fff";
+ *   color: "#fff";
+ *   color: "#000";
+ * }
+ */
+
+function readableColor(color) {
+  var c = parseToRgb(color);
+  return h(c.red) * 0.2126 + h(c.green) * 0.7152 + h(c.blue) * 0.0722 > 0.179 ? '#000' : '#fff';
+}
+
+// Don’t inline this variable into export because Rollup will remove the /*#__PURE__*/ comment
+var curriedReadableColor = /*#__PURE__*/curry(readableColor); // eslint-disable-line spaced-comment
+
+//      
+
 /**
  * Increases the intensity of a color. Its range is between 0 to 1. The first
  * argument of the saturate function is the amount by how much the color
@@ -3072,6 +3114,7 @@ exports.parseToRgb = parseToRgb;
 exports.placeholder = placeholder;
 exports.position = position;
 exports.radialGradient = radialGradient;
+exports.readableColor = curriedReadableColor;
 exports.rem = rem;
 exports.retinaImage = retinaImage;
 exports.rgb = rgb;

package.json

@@ -4,8 +4,9 @@
   "main": "lib/index.js",
   "jsnext:main": "dist/polished.es.js",
   "module": "dist/polished.es.js",
+  "types": "lib/index.d.ts",
   "scripts": {
-    "build": "npm run build:lib && npm run build:dist && npm run build:flow && npm run build:docs",
+    "build": "npm run build:lib && npm run build:dist && npm run build:flow && npm run build:docs && npm run build:typescript",
     "prebuild:lib": "shx rm -rf lib/*",
     "build:lib": "babel --out-dir lib src --ignore test.js",
     "prebuild:umd": "shx rm -rf dist/*",
@@ -18,13 +19,15 @@
     "postbuild:docs:site": "shx cp CNAME docs/CNAME && shx cp dist/polished.js docs/assets/",
     "build:watch": "npm-watch",
     "build:flow": "flow-copy-source -v -i '{**/test/*.js,**/*.test.js}' src lib",
+    "build:typescript": "tsgen \"lib/**/*.js.flow\" --ignore \"lib/**/_*.js.flow\"",
     "test": "jest src",
+    "typescript": "tsc ./typescript-test.ts --noEmit --target es6 --module es2015 --moduleResolution node",
     "precommit": "lint-staged --verbose",
     "postcommit": "validate-commit-msg",
     "lint": "eslint src",
     "flow": "flow check && flow-coverage-report -i 'src/**/!(*.test).js'",
     "docs": "pushstate-server docs",
-    "prepublish": "npm run build"
+    "prepublish": "npm run build && npm run typescript"
   },
   "lint-staged": {
     "src/**/!(*.test).js": [
@@ -113,5 +116,9 @@
   "jest": {
     "coverageDirectory": "./coverage/",
     "collectCoverage": true
+  },
+  "dependencies": {
+    "tsgen": "^1.0.0",
+    "typescript": "^2.4.2"
   }
 }

src/color/readableColor.js

@@ -1,5 +1,4 @@
 // @flow
-
 import parseToRgb from './parseToRgb'
 import curry from '../internalHelpers/_curry'
 

src/helpers/em.js

@@ -26,5 +26,8 @@ import pixelsto from '../internalHelpers/_pxto'
  */
 
 // Don’t inline this variable into export because Rollup will remove the /*#__PURE__*/ comment
-const em = /*#__PURE__*/ pixelsto('em') // eslint-disable-line spaced-comment
+const em: (
+  value: string | number,
+  base?: string | number,
+) => string = /* #__PURE__*/ pixelsto('em') // eslint-disable-line spaced-comment
 export default em

src/helpers/rem.js

@@ -27,5 +27,8 @@ import pixelsto from '../internalHelpers/_pxto'
  */
 
 // Don’t inline this variable into export because Rollup will remove the /*#__PURE__*/ comment
-const rem = /*#__PURE__*/ pixelsto('rem') // eslint-disable-line spaced-comment
+const rem: (
+  value: string | number,
+  base?: string | number,
+) => string = /*#__PURE__*/ pixelsto('rem') // eslint-disable-line spaced-comment
 export default rem

src/mixins/radialGradient.js

@@ -81,7 +81,7 @@ function radialGradient({
   fallback,
   position,
   shape,
-}: RadialGradientConfiguration) {
+}: RadialGradientConfiguration): Object {
   if (!colorStops || colorStops.length < 2) {
     throw new Error(
       'radialGradient requries at least 2 color-stops to properly render.',

src/mixins/triangle.js

@@ -75,7 +75,7 @@ function triangle({
   width,
   foregroundColor,
   backgroundColor = 'transparent',
-}: TriangleArgs) {
+}: TriangleArgs): Object {
   const unitlessHeight = parseFloat(height)
   const unitlessWidth = parseFloat(width)
   if (isNaN(unitlessHeight) || isNaN(unitlessWidth)) {

typescript-test.ts

@@ -0,0 +1,150 @@
+import * as polished from "./lib/index";
+
+/*
+ * Mixins
+ */
+let clearFix: object = polished.clearFix();
+clearFix = polished.clearFix("&");
+
+let ellipsis: object = polished.ellipsis();
+ellipsis = polished.ellipsis("250px");
+
+const fontFace: object = polished.fontFace({
+  fontFamily: "Sans-Pro",
+  fontFilePath: "path/to/file",
+  fontStretch: "",
+  fontStyle: "",
+  fontVariant: "",
+  fontWeight: "",
+  fileFormats: [""],
+  localFonts: [""],
+  unicodeRange: ""
+});
+
+const hideText: object = polished.hideText();
+
+let hiDPI: string = polished.hiDPI();
+hiDPI = polished.hiDPI(1.5);
+
+let normalize: object = polished.normalize();
+normalize = polished.normalize(true);
+
+let placeholder: object = polished.placeholder({});
+placeholder = polished.placeholder({}, "");
+
+const radialGradient: object = polished.radialGradient({
+  colorStops: ["#00FFFF 0%", "rgba(0, 0, 255, 0) 50%", "#0000FF 95%"],
+  extent: "farthest-corner at 45px 45px",
+  position: "center",
+  shape: "ellipse",
+  fallback: ""
+});
+
+let retinaImage: object = polished.retinaImage("");
+retinaImage = polished.retinaImage("", "");
+retinaImage = polished.retinaImage("", "", "");
+retinaImage = polished.retinaImage("", "", "", "");
+retinaImage = polished.retinaImage("", "", "", "", "");
+
+let selection: object = polished.selection({});
+selection = polished.selection({}, "");
+
+const timingFunctions = polished.timingFunctions("easeInBack");
+
+const triangle = polished.triangle({
+  backgroundColor: "red",
+  foregroundColor: "red",
+  pointingDirection: "right",
+  width: 100,
+  height: 100,
+});
+
+let wordWrap: object = polished.wordWrap();
+wordWrap = polished.wordWrap("");
+
+/*
+ * Colors
+ */
+const adjustHue: string = polished.adjustHue(180, "#448");
+const complement: string = polished.complement("#448");
+const darken: string = polished.darken(0.2, "#FFCD64");
+const desaturate: string = polished.desaturate(0.2, "#CCCD64");
+const grayscale: string = polished.grayscale("#CCCD64");
+
+let hsl: string = polished.hsl(359, 0.75, 0.4);
+hsl = polished.hsl({ hue: 360, saturation: 0.75, lightness: 0.4 });
+
+let hsla: string = polished.hsla(359, 0.75, 0.4, 0.7);
+hsla = polished.hsla({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.7 });
+
+const invert: string = polished.invert("#CCCD64");
+const lighten: string = polished.lighten(0.2, "#CCCD64");
+const mix: string = polished.mix(0.5, "#f00", "#00f");
+const opacify: string = polished.opacify(0.1, "rgba(255, 255, 255, 0.9)");
+const parseToHsl = polished.parseToHsl("rgb(255, 0, 0)");
+const parseToRgb = polished.parseToRgb("rgb(255, 0, 0)");
+const readableColor = polished.readableColor("rgb(255,0,0)");
+
+let rgb: string = polished.rgb(255, 205, 100);
+rgb = polished.rgb({ red: 255, green: 205, blue: 100 });
+
+let rgba: string = polished.rgba(255, 205, 100, 0.7);
+rgba = polished.rgba({ red: 255, green: 205, blue: 100, alpha: 0.7 });
+
+const saturate: string = polished.saturate(0.2, "#CCCD64");
+const setHue: string = polished.setHue(42, "#CCCD64");
+const setLightness: string = polished.setLightness(0.2, "#CCCD64");
+const setSaturation: string = polished.setSaturation(0.2, "#CCCD64");
+const shade: string = polished.shade(0.25, "#00f");
+const tint: string = polished.tint(0.25, "#00f");
+
+let toColorString: string = polished.toColorString({ red: 255, green: 205, blue: 100 });
+toColorString = polished.toColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 });
+toColorString = polished.toColorString({ hue: 240, saturation: 1, lightness: 0.5 });
+toColorString = polished.toColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 });
+
+const transparentize: string = polished.transparentize(0.1, "#fff");
+
+/*
+ * Shorthands
+ */
+const animation: object = polished.animation(["rotate", 1, "ease-in-out"], ["colorchange", "2s"]);
+const backgroundImages: object = polished.backgroundImages("url('/image/background.jpg')", "linear-gradient(red, green)");
+const backgrounds: object = polished.backgrounds("url('/image/background.jpg')", "linear-gradient(red, green)", "center no-repeat");
+const borderColor: object = polished.borderColor("red", null, undefined, "green");
+const borderRadius: object = polished.borderRadius("top", "5px");
+const borderStyle: object = polished.borderStyle("solid", null, undefined, "dashed");
+const borderWidth: object = polished.borderWidth("12px", null, undefined, "24px");
+const buttons: string = polished.buttons(null, undefined, "active");
+const margin: object = polished.margin("12px", null, undefined, "24px");
+const padding: object = polished.padding("12px", null, undefined, "24px");
+
+let position: object = polished.position(null);
+polished.position("absolute", "12px", null, undefined, "24px");
+position = polished.position(null, "12px", null, undefined, "24px");
+position = polished.position(undefined, "12px", null, undefined, "24px");
+
+let size: object = polished.size("");
+size = polished.size("", "");
+
+const textInputs: string = polished.textInputs("active", null, undefined);
+const transitions: object = polished.transitions("opacity 1.0s ease-in 0s", "width 2.0s ease-in 2s");
+
+/*
+ * Helpers
+ */
+const directionalProperty: object = polished.directionalProperty("padding", "12px", null, undefined, "24px");
+
+let em: string = polished.em("12px");
+em = polished.em(12);
+
+let rem: string = polished.rem("12px");
+rem = polished.rem(12);
+
+let modularScale: string = polished.modularScale(2);
+modularScale = polished.modularScale(2, 2);
+modularScale = polished.modularScale(2, "");
+modularScale = polished.modularScale(2, 2, 5);
+modularScale = polished.modularScale(2, 2, "minorSecond");
+
+const stripUnit: number | string = polished.stripUnit("100px");