Cookbook Example: Editable SVG Icon System (vuejs#1361)

* first part of editable icons recipe

* write up the rest of the example

* another round of content

* update post based on chris' edits- mostly readability

Author: sdras

package.json

@@ -25,4 +25,4 @@
     "hexo-server": "^0.2.2",
     "request": "^2.83.0"
   }
-}
+}

src/v2/cookbook/cookbook-contributions.md

@@ -1,12 +1,12 @@
 ---
 title: Cookbook Contributions
 type: cookbook
-order: 1000
+order: 1
 ---
 
 ## What we're looking for
 
-The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach. 
+The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach.
 
 If you're interested in contributing, please initiate collaboration by filing an issue under the tag **cookbook idea** with your concept so that we can help guide you to a successful pull request. After your idea has been approved, please follow the template below as much as possible. Some sections are required, and some are optional. Following the numerical order is strongly suggested, but not required.
 
@@ -33,6 +33,7 @@ _required_
 _required_
 
 Demonstrate the code that would power a common or interesting use case, either by:
+
 1. Walking through a few terse examples of setup, or
 2. Embedding a codepen/jsfiddle example
 
@@ -58,4 +59,4 @@ This section is required when you've provided the section above about avoidance.
 
 ## Thank you
 
-It takes time to contribute to documentation, and if you spend the time to submit a PR this section of our docs, you do so with our gratitude.
+It takes time to contribute to documentation, and if you spend the time to submit a PR this section of our docs, you do so with our gratitude.

src/v2/cookbook/editable-svg-icons.md

@@ -0,0 +1,169 @@
+---
+title: Editable SVG Icon Systems
+type: cookbook
+order: 2
+---
+
+## Base Example
+
+There are many ways to create an SVG Icon System, but one method that takes advantage of Vue's capabilities is to create editable inline icons as components. Some of the advantages of this way of working is:
+
+* They are easy to edit on the fly
+* They are animatable
+* You can use standard props and defaults to keep them to a typical size or alter them if you need to
+* They are inline, so no HTTP requests are necessary
+* They can be made accessible dynamically
+
+First, we'll create a folder for all of the icons, and name them in a standardized fashion for easy retrieval:
+
+> components/icons/IconBox.vue
+> components/icons/IconCalendar.vue
+> components/icons/IconEnvelope.vue
+
+Here's an example repo to get you going, where you can see the entire setup: [https://github.com/sdras/vue-sample-svg-icons/](https://github.com/sdras/vue-sample-svg-icons/)
+
+![Documentation site](https://s3-us-west-2.amazonaws.com/s.cdpn.io/28963/screendocs.jpg 'Docs demo')
+
+We'll create a base icon (`IconBase.vue`) component that uses a scoped slot.
+
+```html
+<template>
+  <svg xmlns="http://www.w3.org/2000/svg"
+    :width="width"
+    :height="height"
+    viewBox="0 0 18 18"
+    :aria-labelledby="iconName"
+    role="presentation"
+  >
+    <title :id="iconName" lang="en">{{iconName}} icon</title>
+    <g :fill="iconColor">
+      <slot />
+    </g>
+  </svg>
+</template>
+```
+
+You can use this base icon as is- the only thing you might need to update is the `viewBox` depending on the `viewBox` of your icons. In the base, we're making the `width`, `height`, `color`, and name of the icon props so that it can be dynamically updated with props. The name will be used for both the title `id` for accessibility, and the `title`.
+
+Our script will look like this, we'll have some defaults so that our icon will be rendered consistently unless we state otherwise:
+
+```js
+export default {
+  props: {
+    iconName: {
+      type: String,
+      default: 'box'
+    },
+    width: {
+      type: [Number, String],
+      default: 18
+    },
+    height: {
+      type: [Number, String],
+      default: 18
+    },
+    iconColor: {
+      type: String,
+      default: 'currentColor'
+    }
+  }
+}
+```
+
+The currentColor property that's the default on the fill will make the icon inherit the color of whatever text surrounds it. We could also pass in a different color as a prop if we wish.
+
+We can use it like so, with the only contents of IconWrite.vue containing the paths inside the icon:
+
+```html
+<icon-base icon-name="write"><icon-write /></icon-base>
+```
+
+Now, if we'd like to make many sizes for the icon, we can do so very easily:
+
+```html
+<p>
+  <!--you can pass in a smaller width and height as props-->
+  <icon-base width="12" height="12" icon-name="write"><icon-write /></icon-base>
+  <!--or you can use the default, which is 18-->
+  <icon-base icon-name="write"><icon-write /></icon-base>
+  <!--or make it a little bigger too :) -->
+  <icon-base width="30" height="30" icon-name="write"><icon-write /></icon-base>
+</p>
+```
+
+<img src="https://s3-us-west-2.amazonaws.com/s.cdpn.io/28963/Screen%20Shot%202018-01-01%20at%204.51.40%20PM.png" width="450" />
+
+## Animatable Icons
+
+Keeping icons in components comes in very handy when you'd like to animate them, especially on an interaction. Inline SVGs have the highest support for interaction of any method. Here's a very basic example of an icon that's animated on click:
+
+```html
+<template>
+  <svg @click="startScissors"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 100 100"
+    width="100"
+    height="100"
+    aria-labelledby="scissors"
+    role="presentation"
+    >
+    <title id="scissors" lang="en">Scissors Animated Icon</title>
+    <path id="bk" fill="#fff" d="M0 0h100v100H0z"/>
+    <g ref="leftscissor">
+      <path d="M..."/>
+      ...
+    </g>
+    <g ref="rightscissor">
+      <path d="M..."/>
+      ...
+    </g>
+  </svg>
+</template>
+```
+
+```js
+import { TweenMax, Sine } from 'gsap'
+
+export default {
+  methods: {
+    startScissors() {
+      this.scissorAnim(this.$refs.rightscissor, 30)
+      this.scissorAnim(this.$refs.leftscissor, -30)
+    },
+    scissorAnim(el, rot) {
+      TweenMax.to(el, 0.25, {
+        rotation: rot,
+        repeat: 3,
+        yoyo: true,
+        svgOrigin: '50 45',
+        ease: Sine.easeInOut
+      })
+    }
+  }
+}
+```
+
+We're applying `refs` to the groups of paths we need to move, and as both sides of the scissors have to move in tandem, we'll create a funciton we can reuse where we'll pass in the `refs`. The use of GreenSock helps resolve animation support and transform-origin issues across browser.
+
+<p data-height="300" data-theme-id="0" data-slug-hash="dJRpgY" data-default-tab="result" data-user="Vue" data-embed-version="2" data-pen-title="Editable SVG Icon System: Animated icon" class="codepen">See the Pen <a href="https://codepen.io/team/Vue/pen/dJRpgY/">Editable SVG Icon System: Animated icon</a> by Vue (<a href="https://codepen.io/Vue">@Vue</a>) on <a href="https://codepen.io">CodePen</a>.</p><script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+
+<p style="margin-top:-30px">Pretty easily accomplished! And easy to update on the fly.</p>
+
+You can see more animated examples in the repo [here](https://github.com/sdras/vue-sample-svg-icons/)
+
+## Additional Notes
+
+Designers may change their minds. Product requirements change. Keeping the logic for the entire icon system in one base component means you can quickly update all of your icons and have it propogate through the whole system. Even with the use of an icon loader, some situations require you to recreate or edit every SVG to make global changes. This method can save you that time and pain.
+
+## When To Avoid This Pattern
+
+This type of SVG icon system is really useful when you have a number of icons that are used in different ways throughout your site. If you're repeating the same icon many times on one page (e.g. a giant table a delete icon in each row), it might make more sense to have all of the sprites compiled into a sprite sheet and use `use` tags to load them.
+
+## Alternative Patterns
+
+Other tooling to help manage SVG icons includes:
+
+* [svg-sprite-loader](https://github.com/kisenka/svg-sprite-loader)
+* [svgo-loader](https://github.com/rpominov/svgo-loader)
+
+These tools bundle SVGs at compile time, but make them a little harder to edit during runtime, because `use` tags can have strange cross-browser issues when doing anything more complex. They also leave you with two nested `viewBox` properties and thus two coordinate systems. This makes the implementation a little more complex.

src/v2/cookbook/index.md

@@ -12,13 +12,13 @@ order: 0
 
 How is the cookbook different from the guide? Why is this necessary?
 
-- __Greater Focus__: In the guide, we're essentially telling a story. Each section builds on and assumes knowledge from each previous section. In the cookbook, each recipe can and should stand on its own. This means recipes can focus on one specific aspect of Vue, rather than having to give a general overview.
+* **Greater Focus**: In the guide, we're essentially telling a story. Each section builds on and assumes knowledge from each previous section. In the cookbook, each recipe can and should stand on its own. This means recipes can focus on one specific aspect of Vue, rather than having to give a general overview.
 
-- __Greater Depth__: To avoid making the guide too long, we try to include only the simplest possible examples to help you understand each feature. Then we move on. In the cookbook, we can include more complex examples, combining features in interesting ways. Each recipe can also be as long and detailed as it needs to be, in order to fully explore its niche.
+* **Greater Depth**: To avoid making the guide too long, we try to include only the simplest possible examples to help you understand each feature. Then we move on. In the cookbook, we can include more complex examples, combining features in interesting ways. Each recipe can also be as long and detailed as it needs to be, in order to fully explore its niche.
 
-- __Teaching JavaScript__: In the guide, we assume at least intermediate familiarity with ES5 JavaScript. For example, we won't explain how `Array.prototype.filter` works in a computed property that filters a list. In the cookbook however, essential JavaScript features (including ES6/2015+) can be explored and explained in the context of how they help us build better Vue applications.
+* **Teaching JavaScript**: In the guide, we assume at least intermediate familiarity with ES5 JavaScript. For example, we won't explain how `Array.prototype.filter` works in a computed property that filters a list. In the cookbook however, essential JavaScript features (including ES6/2015+) can be explored and explained in the context of how they help us build better Vue applications.
 
-- __Exploring the Ecosystem__: For advanced features, we assume some ecosystem knowledge. For example, if you want to use single-file components in Webpack, we don't explain how to configure the non-Vue parts of the Webpack config. In the cookbook, we have the space to explore these ecosystem libraries in more depth - at least to the extent that is universally useful for Vue developers.
+* **Exploring the Ecosystem**: For advanced features, we assume some ecosystem knowledge. For example, if you want to use single-file components in Webpack, we don't explain how to configure the non-Vue parts of the Webpack config. In the cookbook, we have the space to explore these ecosystem libraries in more depth - at least to the extent that is universally useful for Vue developers.
 
 ## Guidelines for Recipes
 
@@ -39,4 +39,3 @@ Recipes should generally:
 > 7. Explain the pros and cons of your strategy, including when it is and isn't appropriate
 
 > 8. Mention alternative solutions, if relevant, but leave in-depth explorations to a separate recipe
-