Allow Gridicons library to be imported by component (#283)

The goal of this PR is to prepare Gridicons to be imported by component. To use the external Gridicon at the moment we do: import Gridicon from 'gridicons'; <Gridicon icon="external" /> After this PR lands, with the new API we could also import the individual component directly: import GridiconExternal from 'gridicons/dist/external'; <GridiconExternal /> By doing so, we're able to ship only the SVGs that the user needs and the size impact of using the Gridicons library in any project would become as minimal as it can be. For example, at the moment, to use the external Gridicon (278 bytes) in any project you'll pull 81K because the Gridicon component contains the whole icon set. By importing the individual component, you'll only pull 1,2K.
Automattic · Mar 14, 2018 · 287034f · 287034f
1 parent 49db653
commit 287034f
Show file tree

Hide file tree

Showing 13 changed files with 281 additions and 213 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,5 +3,6 @@ node_modules/
 .idea/
 svg-min-react/
 build/
+dist/
 .DS_Store
 package-lock.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 _The versioning refers to the React component build._
 
+#### v3.0.0 (2018-03-14)
+* React: remove obsolete @ssr-ready pragma from components.
+* React: allow importing individual icons in CommonJS module formats.
+* React: substitute React.PureComponent for a JavaScript function, to minimize the bundle size of transpiled CommonJS files as much as possible.
+* Build: use template literals to create the React components and centralize the _icon needs offset_ logic in the svg-to-react Grunt task.
+* Build: renamed `build/` to `dist/`, which is now part of the gridicons npm package.
+
 #### v2.1.3 (2018-02-22)
 * Icon added: "Shutter"
 

diff --git a/Gruntfile.js b/Gruntfile.js
@@ -98,10 +98,14 @@ module.exports = function( grunt ) {
 				]
 			},
 			dist: {
-				files: {
-					"build/index.js": "build/index.jsx",
-					"build/example.js": "build/example.jsx"
-				}
+				files: [{
+					expand: true,
+					cwd: 'build/',
+					src: [ '**/*.jsx' ],
+					dest: 'dist/',
+					ext: '.js',
+					filter: 'isFile'
+				}]
 			}
 		},
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 The [Calypso](https://github.com/Automattic/wp-calypso/) / [WordPress.com](https://wordpress.com) official icon set.
 
-## Using the Gridicon Component in your project:
+## Using the Gridicon Component in your project
 
 Note that this component requires [react](https://www.npmjs.com/package/react) to be installed in your project. If you don't want to use React, you can simply include the raw `.svg` files from the [`svg-min`](https://github.com/Automattic/gridicons/tree/master/svg-min) folder.
 
@@ -16,6 +16,8 @@ npm install gridicons --save
 
 #### Usage
 
+You can either import the whole iconset and decide at run-time which icon to use:
+
 ```
 import Gridicon from 'gridicons';
 //...
@@ -24,9 +26,21 @@ render() {
 }
 ```
 
+Or import icons individually:
+
+```
+import GridiconAddImage from 'gridicons/dist/add-image';
+//...
+render() {
+    return <GridiconAddImage />;
+}
+```
+
+If you use only a few icons, the recommended way of using the Gridicon library is to import them individually. At the moment of writing this, individual icons are between 1K and 2K, and the file containing the whole iconset sits at 92K.
+
 #### Props
 
-* `icon`: String - the icon name.
+* `icon`: String - the icon name. This is ignored when importing icons individually.
 * `size`: Number - (default: 24) set the size of the icon.
 * `onClick`: Function - (optional) if you need a click callback.
 
@@ -35,7 +49,6 @@ render() {
 * The icon set is made to be used exactly at these pixel sizes: 12, 18, 24, 36, 48, 54, 72.
 * `gridicon-my-sites` as it's a small-size version of the WordPress logo, shouldn't be used larger than 36px. If you need to use the WordPress logo in larger sizes, see the [Social Logos project](https://github.com/Automattic/social-logos).
 
-
 ## Icon Set Style Guidelines
 
 - 24dp base grid
@@ -72,7 +85,7 @@ Note that the icons in this set are tied to be used in [Calypso](https://github.
 1. Switch to the branch (i.e. Pull Request) with the new icon.
 2. Review the SVG source of the new icons to make sure they are clean and readable.
 3. Check pixel sharpness: open in Illustrator (with "Pixel Preview") or Sketch (with "Show Pixels"), adjust if needed.
-4. Run `grunt` command from terminal. It will generate `svg-min`, React (`build`), `svg-sprite`, `pdf`, `php`, and `docs`.
+4. Run `grunt` command from terminal. It will generate `svg-min`, `build`, `dist`, `svg-sprite`, `pdf`, `php`, and `docs`.
 5. Commit
 6. Merge & delete branch
 
@@ -81,19 +94,19 @@ Note that the icons in this set are tied to be used in [Calypso](https://github.
 
 This icon set uses a few automation scripts to ease the generation of new icons in a reliable way. In short, we require `node` and `grunt`. For detailed instructions check [the installation page](https://github.com/Automattic/gridicons/wiki/Installation).
 
-Once you checkout the repo run `npm install` in the `gridicons` folder. 
-To generate all the fonts, svgs and so on you run `npm run build` 
+Once you checkout the repo run `npm install` in the `gridicons` folder.
+To generate all the fonts, svgs and so on you run `npm run build`
 
 ## Publishing to npm
 
 Note: to proceed with this you need to have write authorization to npm.
 
-1. Create a new PR with updated `CHANGELOG.md` and updated version in `package.json` (i.e. `1.2.3-alpha.1`), see an example [here](https://github.com/Automattic/gridicons/pull/275). 
-2. In the "CHANGELOG.md" make sure to check all the previous commits since the previous versioned release. 
+1. Create a new PR with updated `CHANGELOG.md` and updated version in `package.json` (i.e. `1.2.3-alpha.1`), see an example [here](https://github.com/Automattic/gridicons/pull/275).
+2. In the "CHANGELOG.md" make sure to check all the previous commits since the previous versioned release.
 3. Pre-publish that PR branch on npm with `npm publish --tag next` ([more info](https://docs.npmjs.com/cli/dist-tag)). Running the `npm publish --tag next` command will send the data that you have localy to npm. Having the alpha version in the `package.json` file will create a newly tagged version npm package. Use `npm view gridicons` to look at the list of current tags. You do not need to commit changes to github in order to publish to npm, but it is recommended so folks testing know what's available.
-4. Create a new update PR in a repository that makes use of Gridicons and run `npm install gridicons@next --save` (which will update `packages.json`). If you're creating the PR in [Calypso](https://github.com/Automattic/wp-calypso) and you get warnings, it might need to regenerate the shrinkwrap, in which case run `npm run update-deps`. See an example [here](https://github.com/Automattic/wp-calypso/pull/17601). 
+4. Create a new update PR in a repository that makes use of Gridicons and run `npm install gridicons@next --save` (which will update `packages.json`). If you're creating the PR in [Calypso](https://github.com/Automattic/wp-calypso) and you get warnings, it might need to regenerate the shrinkwrap, in which case run `npm run update-deps`. See an example [here](https://github.com/Automattic/wp-calypso/pull/17601).
 5. Test if the new icons show up, and there are no regressions in the previous icons. Take a look at the `http://calypso.localhost:3000/devdocs/design/gridicons` for example.
-6. If changes look good, remove the alpha postfix in the version (i.e. `1.2.3-alpha.1` to `1.2.3`) on both repositories PRs. 
+6. If changes look good, remove the alpha postfix in the version (i.e. `1.2.3-alpha.1` to `1.2.3`) on both repositories PRs.
 7. Merge the Gridicons PR.
 8. Tag the release on GitHub: `git tag -a v1.2.3 -m "Release v1.2.3"` (and push `git push origin v1.2.3`).
 9. Check if it shows up in the [Releases list](https://github.com/Automattic/gridicons/releases).
@@ -106,11 +119,11 @@ Gridicons is licensed under [GNU General Public License v2 (or later)](./LICENSE
 
 ## More notes on publishing to npm
 You need to have a npm user account. [Create one here](https://www.npmjs.com/signup).
-Once you have created it, set up the account on you machine via 
+Once you have created it, set up the account on you machine via
 $ `npm adduser`
 
-Setup the 2fa with npm 
-$ `npm profile enable-2fa` 
+Setup the 2fa with npm
+$ `npm profile enable-2fa`
 
-Now everytime before you can publish 
+Now everytime before you can publish
 You will be asked for a your [2FA code (OPT)](https://en.wikipedia.org/wiki/One-time_password)
diff --git a/grunt-tasks/svg-to-react.js b/grunt-tasks/svg-to-react.js
@@ -3,52 +3,64 @@
 
 module.exports = function( grunt ) {
   grunt.registerMultiTask( 'svg-to-react', 'Output a react component for SVGs', function() {
-    var component = '';
-    var componentExample = '';
-    var filesDest;
+		let components = '';
+		let componentsExample = '';
+		let filesDest;
+		const prepareIndividualIcon = require( '../sources/react/template-individual-icon' );
+		const prepareAllIcons = require( '../sources/react/template-all-icons' );
+		const prepareDevDocsExample = require( '../sources/react/template-devdocs-example' );
+		const {
+			iconsThatNeedOffset,
+			iconsThatNeedOffsetX,
+			iconsThatNeedOffsetY
+		} = require( '../sources/react/icons-offset' );
 
-    // Create a switch() case for each svg file
     this.files.forEach( function( files ) {
       files.src.forEach( function( svgFile ) {
-        // Clean up the filename to use for the react components
-        var name = svgFile.split( '.' );
-        name = name[0];
+        // Name to be used by the react components
+        let name = svgFile.split( '.' )[ 0 ];
 
         // Grab the relevant bits from the file contents
-        var fileContent = grunt.file.read( files.cwd + svgFile );
+        let fileContent = grunt.file.read( files.cwd + svgFile );
 
         // Add className, height, and width to the svg element
         fileContent = fileContent.slice( 0, 4 ) +
               ' className={ iconClass } height={ size } width={ size } onClick={ onClick } { ...otherProps }' +
               fileContent.slice( 4, -6 ) +
               fileContent.slice( -6 );
 
-        // Output the case for each icon
-        component += "			case '" + name + "':\n" +
+        // Holds the switch's cases for every icon
+        components += "			case '" + name + "':\n" +
                   "				svg = " + fileContent + ";\n" +
-                  "				break;\n";;
+                  "				break;\n";
 
-        // Example Document
+        // Holds the Example Document
         name = name.replace( 'gridicons-', '' );
-        componentExample += '				<Gridicon icon="' + name + '" size={ 48 } onClick={ this.handleClick.bind( this, \'' + name + '\' ) } />\n';
+        componentsExample += '				<Gridicon icon="' + name + '" size={ 48 } onClick={ this.handleClick.bind( this, \'' + name + '\' ) } />\n';
 
+				// Prepare and write to disk every individual icon separately
+				grunt.file.write( files.dest + name + '.jsx', prepareIndividualIcon( {
+					name,
+					component: fileContent,
+					iconsThatNeedOffset,
+					iconsThatNeedOffsetX,
+					iconsThatNeedOffsetY,
+				} ) );
 
       } );
 
       filesDest = files.dest;
     } );
 
-    // React Component Wrapping
-    component = grunt.file.read( 'sources/react/index-header.jsx' ) + component;
-    component += grunt.file.read( 'sources/react/index-footer.jsx' );
+    // Prepare and write to disk the Design Docs Example component
+		grunt.file.write( filesDest + 'example.jsx', prepareDevDocsExample( componentsExample ) );
 
-    // Design Docs Wrapping
-    componentExample = grunt.file.read( 'sources/react/example-header.jsx' ) + componentExample;
-    componentExample +=	grunt.file.read( 'sources/react/example-footer.jsx' );
-
-
-    // Write the React component to gridicon/index.jsx
-    grunt.file.write( filesDest + 'index.jsx', component );
-    grunt.file.write( filesDest + 'example.jsx', componentExample );
+    // Prepare and write to disk the Gridicon React component
+    grunt.file.write( filesDest + 'index.jsx', prepareAllIcons( {
+			components,
+			iconsThatNeedOffset,
+			iconsThatNeedOffsetX,
+			iconsThatNeedOffsetY,
+		} ) );
   } );
 };
diff --git a/package.json b/package.json
@@ -1,7 +1,10 @@
 {
   "name": "gridicons",
-  "version": "2.1.3",
-  "main": "build/index.js",
+  "version": "3.0.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist/"
+  ],
   "scripts": {
     "build": "grunt --verbose",
     "prepublish": "npm run build"
@@ -14,10 +17,6 @@
     "url": "https://github.com/Automattic/gridicons"
   },
   "license": "GPL-2.0+",
-  "files": [
-    "build/index.js",
-    "build/example.js"
-  ],
   "dependencies": {
     "prop-types": "^15.5.7"
   },

diff --git a/sources/react/example-footer.jsx b/sources/react/example-footer.jsx
diff --git a/sources/react/icons-offset.js b/sources/react/icons-offset.js
@@ -0,0 +1,87 @@
+const iconsThatNeedOffset = [
+	'gridicons-add-outline',
+	'gridicons-add',
+	'gridicons-align-image-center',
+	'gridicons-align-image-left',
+	'gridicons-align-image-none',
+	'gridicons-align-image-right',
+	'gridicons-attachment',
+	'gridicons-bold',
+	'gridicons-bookmark-outline',
+	'gridicons-bookmark',
+	'gridicons-calendar',
+	'gridicons-cart',
+	'gridicons-create',
+	'gridicons-custom-post-type',
+	'gridicons-external',
+	'gridicons-folder',
+	'gridicons-heading',
+	'gridicons-help-outline',
+	'gridicons-help',
+	'gridicons-history',
+	'gridicons-info-outline',
+	'gridicons-info',
+	'gridicons-italic',
+	'gridicons-layout-blocks',
+	'gridicons-link-break',
+	'gridicons-link',
+	'gridicons-list-checkmark',
+	'gridicons-list-ordered',
+	'gridicons-list-unordered',
+	'gridicons-menus',
+	'gridicons-minus',
+	'gridicons-my-sites',
+	'gridicons-notice-outline',
+	'gridicons-notice',
+	'gridicons-plus-small',
+	'gridicons-plus',
+	'gridicons-popout',
+	'gridicons-posts',
+	'gridicons-scheduled',
+	'gridicons-share-ios',
+	'gridicons-star-outline',
+	'gridicons-star',
+	'gridicons-stats',
+	'gridicons-status',
+	'gridicons-thumbs-up',
+	'gridicons-textcolor',
+	'gridicons-time',
+	'gridicons-trophy',
+	'gridicons-user-circle',
+	'gridicons-reader-follow',
+	'gridicons-reader-following'
+];
+const iconsThatNeedOffsetY = [
+	'gridicons-align-center',
+	'gridicons-align-justify',
+	'gridicons-align-left',
+	'gridicons-align-right',
+	'gridicons-arrow-left',
+	'gridicons-arrow-right',
+	'gridicons-house',
+	'gridicons-indent-left',
+	'gridicons-indent-right',
+	'gridicons-minus-small',
+	'gridicons-print',
+	'gridicons-sign-out',
+	'gridicons-stats-alt',
+	'gridicons-trash',
+	'gridicons-underline',
+	'gridicons-video-camera'
+];
+const iconsThatNeedOffsetX = [
+	'gridicons-arrow-down',
+	'gridicons-arrow-up',
+	'gridicons-comment',
+	'gridicons-clear-formatting',
+	'gridicons-flag',
+	'gridicons-menu',
+	'gridicons-reader',
+	'gridicons-strikethrough'
+];
+
+module.exports = {
+	iconsThatNeedOffset,
+	iconsThatNeedOffsetX,
+	iconsThatNeedOffsetY,
+};
diff --git a/sources/react/index-footer.jsx b/sources/react/index-footer.jsx