Merge pull request #14 from ovh-ux/feat/sprite

feat(sprite): add sprite feature

Author: blaryjp

README.md

@@ -19,6 +19,8 @@ This stack core is to be included in your main project and sets up many Gulp tas
 - webpack module bundling
 - SVG => Font Icons compiling with support for adding mixins and classes to SCSS along with a demo page
 - Drupal file watching to trigger Drush cache clears
+- Copy any files to an other location
+- Sprite generator (with Retina Display support)
 
 All is easily configurable by changing values in your `gulpfile.yml` file in your project. These values are merged into the `gulpfile.default.yml` file - look there for the available options and defaults.
 

docs/features/sprite.md

@@ -0,0 +1,52 @@
+Uses [gulp.spritesmith](https://github.com/twolfson/gulp.spritesmith). Grabs a folder of images and turns them into a sprite, creates a Sass mixin and class for each based on filename.
+
+A documentation for SCSS features is available [here](https://www.bignerdranch.com/blog/css-sprite-management-with-gulp-part2/).
+
+## Usage
+
+Given a file named `facebook.png`, you can use this Sass mixin:
+
+```scss
+@include sprite('sprite-facebook');
+```
+
+Or this HTML class:
+
+```html
+<span class="sprite-facebook"></span>
+```
+
+### Retina Display support
+
+You can generate a second sprite for Retina Display.
+First, you need to duplicates all your images and append "@2x" in the filename. For example: "facebook.png" and "[email protected]".
+
+After enabled it, you can now use the mixin:
+
+```scss
+@include retina-sprite('sprite-facebook');
+```
+
+It will automatically take sprite@2x for Retina Display, and normal sprite for others.
+
+
+## Commands
+
+- `gulp sprite` - Generates the sprite
+- `gulp watch:sprite` - Watch for images modifed and regenerate the sprite
+
+## Config
+
+- `config.sprite.src` - Array or String of globbed PNG files
+- `config.sprite.imgDest` - Destination directory for the sprite image file
+- `config.sprite.cssDest` - Destination directory for the sprite SCSS file
+- `config.sprite.imgName` - Name of the sprite image file
+- `config.sprite.cssName` - Name of the sprite SCSS file
+- `config.sprite.imgPathPrefix` - Sprite image path prefix
+- `config.sprite.spritesheetName` - Name of the sprite
+- `config.sprite.imagemin` - Enable imagemin compression for the sprite image file
+- `config.sprite.retina.enabled` - Enable retina sprite generation
+- `config.sprite.retina.imgName` - Name of the retina sprite image file
+- `config.sprite.retina.filter` - Images filter that match the retina files
+
+---

docs/index.md

@@ -14,6 +14,8 @@ This stack core is to be included in your main project and sets up many Gulp tas
 - webpack module bundling
 - SVG => Font Icons compiling with support for adding mixins and classes to SCSS along with a demo page
 - Drupal file watching to trigger Drush cache clears
+- Copy any files to an other location
+- Sprite generator (with Retina Display support)
 
 All is easily configurable by changing values in your `gulpfile.yml` file in your project. These values are merged into the `gulpfile.default.yml` file - look there for the available options and defaults.
 

gulpfile.default.yml

@@ -86,6 +86,22 @@ icons:
     - eot
     - woff
     - svg
+sprite:
+  enabled: false
+  src:
+    - images/sprite/*.png
+  imgDest: dist/
+  cssDest: scss/base/
+  imgName: sprite.png
+  cssName: _sprite.scss
+  imgPathPrefix: ../dist/
+  spritesheetName: sprite
+  imagemin: true
+  retina:
+    enabled: false
+    imgName: [email protected]
+    filter:
+      - images/sprite/*@2x.png
 patternLab:
   enabled: false
   configFile: pattern-lab/config/config.yml

index.js

@@ -19,6 +19,10 @@ module.exports = (gulp, userConfig, tasks) => {
     require('./lib/icons')(gulp, config, tasks);
   }
 
+  if (config.sprite.enabled) {
+    require('./lib/sprite')(gulp, config, tasks);
+  }
+
   if (config.js.enabled) {
     require('./lib/js')(gulp, config, tasks);
   }

lib/sprite.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const gulpif = require('gulp-if');
+const join = require('path').join;
+const del = require('del');
+const spritesmith = require('gulp.spritesmith');
+const buffer = require('vinyl-buffer');
+const imagemin = require('gulp-imagemin');
+const merge = require('merge-stream');
+
+module.exports = (gulp, config, tasks) => {
+  function sprite() {
+    const spriteData = gulp.src(config.sprite.src)
+      .pipe(spritesmith({
+        imgName: config.sprite.imgName,
+        imgPath: `${config.sprite.imgPathPrefix}${config.sprite.imgName}`,
+        cssName: config.sprite.cssName,
+        cssSpritesheetName: config.sprite.spritesheetName,
+        retinaSrcFilter: config.sprite.retina.enabled ? config.sprite.retina.filter : undefined,
+        retinaImgName: config.sprite.retina.enabled ? config.sprite.retina.imgName : undefined,
+        retinaImgPath: config.sprite.retina.enabled ? `${config.sprite.imgPathPrefix}${config.sprite.retina.imgName}` : undefined,
+        cssRetinaSpritesheetName: config.sprite.retina.enabled ? `${config.sprite.spritesheetName}-2x` : undefined,
+        cssVarMap(datas) {
+          // eslint-disable-next-line no-param-reassign
+          datas.name = `${config.sprite.spritesheetName}-${datas.name}`;
+        }
+      }));
+
+    // Pipe image stream through image optimizer and onto disk
+    const imgStream = spriteData.img
+      // DEV: We must buffer our stream into a Buffer for `imagemin`
+      .pipe(buffer())
+      .pipe(gulpif(config.sprite.imagemin, imagemin()))
+      .pipe(gulp.dest(config.sprite.imgDest));
+
+    // Pipe CSS stream onto disk
+    const cssStream = spriteData.css
+      .pipe(gulp.dest(config.sprite.cssDest));
+
+    // Return a merged stream to handle both `end` events
+    return merge(imgStream, cssStream);
+  }
+
+  sprite.description = 'Generates a sprite (img and scss files).';
+
+  gulp.task('sprite', sprite);
+
+  gulp.task('clean:sprite', (done) => {
+    del([
+      join(config.sprite.imgDest, config.sprite.imgName),
+      join(config.sprite.cssDest, config.sprite.cssName)
+    ], { force: true }).then(() => {
+      done();
+    });
+  });
+
+  gulp.task('watch:sprite', () => {
+    gulp.watch(config.sprite.src, sprite);
+  });
+
+  tasks.watch.push('watch:sprite');
+
+  tasks.compile.push('sprite');
+
+  tasks.clean.push('clean:sprite');
+};

mkdocs.yml

@@ -9,6 +9,7 @@ pages:
     - JS: features/js.md
     - Webpack: features/webpack.md
     - Icons: features/icons.md
+    - Sprite: features/sprite.md
     - Drupal-Drush: features/drupal-drush.md
     - Browsersync: features/browser-sync.md
     - Copy: features/copy.md

package.json

@@ -45,6 +45,7 @@
     "gulp-flatten": "^0.4.0",
     "gulp-iconfont": "^9.1.0",
     "gulp-if": "^2.0.2",
+    "gulp-imagemin": "^4.1.0",
     "gulp-inject": "^4.3.0",
     "gulp-notify": "^3.2.0",
     "gulp-plumber": "^1.2.0",
@@ -54,14 +55,17 @@
     "gulp-sourcemaps": "^2.6.4",
     "gulp-stylelint": "^6.0.0",
     "gulp-uglify": "^3.0.0",
+    "gulp.spritesmith": "^6.9.0",
     "js-yaml": "^3.10.0",
     "lodash": "^4.17.5",
     "main-bower-files": "^2.13.1",
+    "merge-stream": "^1.0.1",
     "node-notifier": "^5.2.1",
     "sassdoc": "^2.5.0",
     "stylelint": "^8.4.0",
     "stylelint-scss": "^2.3.0",
     "through2": "^2.0.3",
+    "vinyl-buffer": "^1.0.1",
     "webpack": "^3.11.0"
   },
   "devDependencies": {