Merge pull request #5 from geoblink/add-helper-to-mock-pro-icons

Add helper to mock pro icons

.eslintignore

@@ -1,3 +1,4 @@
 node_modules/*
 dist/*
 test/unit/coverage/*
+public/*

.github/README.md

@@ -0,0 +1,76 @@
+[![NPM](https://img.shields.io/npm/v/@geoblink/design-system)](https://www.npmjs.com/package/@geoblink/design-system)
+[![Build Status](https://travis-ci.com/geoblink/design-system.svg?branch=master)](https://travis-ci.com/geoblink/design-system)
+[![Codecov](https://img.shields.io/codecov/c/gh/geoblink/design-system)](https://codecov.io/gh/geoblink/design-system)
+
+## Getting started
+
+To install this library first you have to add it to your dependencies:
+
+```sh
+yarn add @geoblink/design-system
+```
+
+```sh
+npm i -P @geoblink/design-system
+```
+
+After that, you must install it in your Vue instance:
+
+```js{2,6}
+import Vue from 'vue'
+import GeoblinkDesignSystem from '@geoblink/design-system'
+
+// ...
+
+Vue.use(GeoblinkDesignSystem)
+
+// ...
+```
+
+Finally you have to import the styles.
+You can import the built CSS styles or the raw SCSS file (which include the design tokens as variables):
+
+```css
+@import '~@geoblink/design-system/dist/system.css';
+```
+
+```scss
+@import '~@geoblink/design-system/dist/system.utils.scss';
+```
+
+Depending on your bundler settings you can import it in your JavaScript bundle, too:
+
+```js
+import '@geoblink/design-system/dist/system.css'
+```
+
+```js
+import '@geoblink/design-system/dist/system.utils.scss'
+```
+
+Finally you'll be able use any component from the Design System like they are
+used in the demos:
+
+```vue
+<template>
+  <geo-primary-button @click="doSomething()">
+    Do something!
+  </geo-primary-button>
+</template>
+
+<script>
+export default {
+  methods: {
+    doSomething () {
+      alert('Do something!')
+    }
+  }
+}
+</script>
+```
+
+![Button example](https://raw.githubusercontent.com/geoblink/design-system/master/.github/button-example.png)
+
+## Documentation
+
+Documentation for latest stable version is available at [https://geoblink-design-system.now.sh/](https://geoblink-design-system.now.sh/).

.postcssrc.js

@@ -0,0 +1,10 @@
+// https://github.com/michael-ciniawsky/postcss-load-config
+
+module.exports = {
+  plugins: {
+    'postcss-import': {},
+    'postcss-url': {},
+    // to edit target browsers: use "browserslist" field in package.json
+    autoprefixer: {}
+  },
+}

.vuepress/enhanceApp.js

@@ -7,54 +7,16 @@ import { fab } from '@fortawesome/free-brands-svg-icons'
 import { fas } from '@fortawesome/free-solid-svg-icons'
 import { far } from '@fortawesome/free-regular-svg-icons'
 
+import mockFontAwesomeProIcons from '../src/utils/mockFontAwesomeProIcons'
 import GeoblinkDesignSystem from '../src/system'
 
 // We only want to load this in client-side rendering.
 if (typeof window !== 'undefined') {
   require('../src/utils/webFontLoader')
 }
 
-const _ = require('@geoblink/lodash-mixins').default(require('lodash'))
-
-const iconsToMock = [
-  'faChevronUp',
-  'faChevronDown',
-  'faChevronLeft',
-  'faChevronRight',
-  'faStepBackward',
-  'faStepForward',
-  'faCaretUp',
-  'faCaretDown',
-  'faLock',
-  'faUpload',
-  'faCheckCircle',
-  'faExclamationTriangle',
-  'faLightbulb',
-  'faThumbsUp',
-  'faEllipsisV',
-  'faTimes',
-  'faCheck',
-  'faSearch'
-]
-
-const mockedFalIcons = _.mapValues(_.pick(fas, iconsToMock), function (original) {
-  return _.assign({}, original, {
-    prefix: 'fal'
-  })
-})
-
-const nonExistingIconsToMock = {
-  'external-link-square': 'faExternalLinkSquareAlt',
-  'lock-alt': 'faLock'
-}
-const mockedNonExistingIcons = _.mapValues(nonExistingIconsToMock, function (mockedIconKey, originalIconName) {
-  return _.assign({}, fas[mockedIconKey], {
-    prefix: 'fal',
-    iconName: originalIconName
-  })
-})
-
-library.add(fab, fas, far, mockedFalIcons, mockedNonExistingIcons)
+library.add(fab, fas, far)
+mockFontAwesomeProIcons(library)
 
 export default ({ Vue }) => {
   Vue.component('font-awesome-icon', FontAwesomeIcon)

.vuepress/styles/index.styl

@@ -4,4 +4,8 @@
 .theme-default-content table
   display table
   table-layout: fixed
-  width: 100%
+  width: 100%
+
+  th, td
+    text-overflow: ellipsis;
+    overflow: hidden;

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 29.1.0
+
+New:
+
+- Export `mockFontAwesomeProIcons` to make it easier to use the Design System without FontAwesome Pro.
+
 ## 29.0.0
 
 Breaking:

README.md

@@ -14,7 +14,3 @@ features:
   details: We do not make assumptions on the languages and formats supported by your application.
 footer: MIT Licensed | Copyright © 2018-present Geoblink
 ---
-
-[![NPM](https://img.shields.io/npm/v/@geoblink/design-system)](https://www.npmjs.com/package/@geoblink/design-system)
-[![Build Status](https://travis-ci.com/geoblink/design-system.svg?branch=master)](https://travis-ci.com/geoblink/design-system)
-[![Codecov](https://img.shields.io/codecov/c/gh/geoblink/design-system)](https://codecov.io/gh/geoblink/design-system)

build/build-system.js

@@ -86,7 +86,7 @@ function getBuildWebpackConfigTask (id, title, webpackConfig) {
       return new Promise(function (resolve, reject) {
         webpack(webpackConfig, function (err, webpackStats) {
           if (err) return reject(err)
-          if (webpackStats.hasErrors()) return reject(new Error(`${title} failed!`))
+          if (webpackStats.hasErrors()) return reject(new Error(webpackStats.compilation.errors))
 
           ctx.webpackStats = ctx.webpackStats || {}
           ctx.webpackStats[id] = webpackStats

docs/guides/getting-started.md

@@ -48,6 +48,85 @@ import '@geoblink/design-system/dist/system.css'
 import '@geoblink/design-system/dist/system.utils.scss'
 ```
 
+Finally you'll be able use any component from the Design System like they are
+used in the demos:
+
+```vue live
+<template>
+  <geo-primary-button @click="doSomething()">
+    Do something!
+  </geo-primary-button>
+</template>
+
+<script>
+export default {
+  methods: {
+    doSomething () {
+      alert('Do something!')
+    }
+  }
+}
+</script>
+```
+
+## Using icons
+
+We use icons from [FontAwesome](https://fontawesome.com/) library in some
+components but we want neither to force a specific version of the package nor
+to use it at all! So we make this an opt-in behaviour.
+
+To enable icons you have to install [`@fortawesome/vue-fontawesome`](https://www.npmjs.com/package/@fortawesome/vue-fontawesome)
+package and register `font-awesome-icon` globally:
+
+```sh
+yarn add @fortawesome/fontawesome-svg-core
+yarn add @fortawesome/vue-fontawesome
+yarn add @fortawesome/free-solid-svg-icons
+```
+
+```sh
+npm i --save @fortawesome/fontawesome-svg-core
+npm i --save @fortawesome/vue-fontawesome
+npm i --save @fortawesome/free-solid-svg-icons
+```
+
+Afterwards in your main JavaScript entrypoint:
+
+```js
+import Vue from 'vue'
+import { library } from '@fortawesome/fontawesome-svg-core'
+import { faUserSecret } from '@fortawesome/free-solid-svg-icons' // Or any icon you want to use
+import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
+
+library.add(faUserSecret) // Or any icon you want to use
+
+Vue.component('font-awesome-icon', FontAwesomeIcon)
+
+// ...
+```
+
+### Using free icons
+
+By default we use icons from [FontAwesome Pro](https://fontawesome.com/pro).
+Even though we encourage you to consider upgrading to pro, it's possible to use
+[Geoblink Design System](/) without using any paid resource.
+
+To do so, you have to run `mockFontAwesomeProIcons` once in your main JavaScript
+entrypoint:
+
+```js{3,8}
+import Vue from 'vue'
+import { library } from '@fortawesome/fontawesome-svg-core'
+import { mockFontAwesomeProIcons } from '@geoblink/design-system'
+import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
+
+Vue.component('font-awesome-icon', FontAwesomeIcon)
+
+mockFontAwesomeProIcons(library)
+
+// ...
+```
+
 ## Advanced import
 
 It's possible to import only part of the library.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoblink/design-system",
-  "version": "29.0.0",
+  "version": "29.1.0",
   "description": "Geoblink Design System for Vue.js",
   "author": "Geoblink <contact@geoblink.com>",
   "main": "dist/system.js",
@@ -54,6 +54,7 @@
   ],
   "peerDependencies": {
     "@fortawesome/fontawesome-svg-core": "^1.2.2",
+    "@fortawesome/free-solid-svg-icons": "^5.4.1",
     "@fortawesome/vue-fontawesome": "^0.1.1",
     "@geoblink/ajv-extra": "^1.0.7",
     "ajv": "^5.0.0",

src/system.js

@@ -4,6 +4,8 @@
  */
 import instance from '@/utils/vueInstance'
 
+import mockFontAwesomeProIcons from './utils/mockFontAwesomeProIcons'
+
 import '@/styles/styles.scss'
 
 // Defines contexts to require
@@ -53,3 +55,5 @@ export { componentsByName as components }
 export { constantsByComponentName as constants }
 
 export { instance }
+
+export { mockFontAwesomeProIcons }

src/utils/mockFontAwesomeProIcons.js

@@ -0,0 +1,46 @@
+import { fas } from '@fortawesome/free-solid-svg-icons'
+
+const _ = require('lodash')
+
+export default function mockFontAwesomeProIcons (library) {
+  const iconsToMock = [
+    'faChevronUp',
+    'faChevronDown',
+    'faChevronLeft',
+    'faChevronRight',
+    'faStepBackward',
+    'faStepForward',
+    'faCaretUp',
+    'faCaretDown',
+    'faLock',
+    'faUpload',
+    'faCheckCircle',
+    'faExclamationTriangle',
+    'faLightbulb',
+    'faThumbsUp',
+    'faEllipsisV',
+    'faTimes',
+    'faCheck',
+    'faSearch'
+  ]
+
+  const mockedFalIcons = _.mapValues(_.pick(fas, iconsToMock), function (original) {
+    return _.assign({}, original, {
+      prefix: 'fal'
+    })
+  })
+
+  const nonExistingIconsToMock = {
+    'external-link-square': 'faExternalLinkSquareAlt',
+    'lock-alt': 'faLock'
+  }
+  const mockedNonExistingIcons = _.mapValues(
+    nonExistingIconsToMock,
+    (mockedIconKey, originalIconName) => _.assign({}, fas[mockedIconKey], {
+      prefix: 'fal',
+      iconName: originalIconName
+    })
+  )
+
+  library.add(mockedFalIcons, mockedNonExistingIcons)
+}