feat(fxLayoutGap): add gutter functionality to layout-gap

* Apply negative margin and positive padding as browser-agnostic
  hack for grid gutter
* The new feature is activated by appending `grid` to any
  `fxLayoutGap` input, e.g.
  `fxLayoutGap="10px grid"`

src/apps/demo-app/src/app/layout/docs-layout/docs-layout.component.ts

@@ -5,6 +5,7 @@ import {Component} from '@angular/core';
   template: `
     <demo-layout-alignment class="small-demo"></demo-layout-alignment>
     <demo-layout-fill class="small-demo"></demo-layout-fill>
+    <demo-layout-gap class="small-demo"></demo-layout-gap>
     <demo-flex-row-fill class="small-demo"></demo-flex-row-fill>
     <demo-flex-row-fill-wrap class="small-demo"></demo-flex-row-fill-wrap>
     <demo-flex-attribute-values class="small-demo"></demo-flex-attribute-values>

src/apps/demo-app/src/app/layout/layout-gap/layout-gap.component.spec.ts

@@ -0,0 +1,25 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { LayoutGapComponent } from './layout-gap.component';
+
+describe('LayoutGapComponent', () => {
+  let component: LayoutGapComponent;
+  let fixture: ComponentFixture<LayoutGapComponent>;
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [ LayoutGapComponent ]
+    })
+    .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(LayoutGapComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

src/apps/demo-app/src/app/layout/layout-gap/layout-gap.component.ts

@@ -0,0 +1,70 @@
+import {Component} from '@angular/core';
+
+const DIRECTIONS = ['row', 'row-reverse', 'column', 'column-reverse'];
+
+@Component({
+  selector: 'demo-layout-gap',
+  template: `
+    <mat-card class="card-demo">
+      <mat-card-title><a href="" target="_blank">Layout Gap</a></mat-card-title>
+      <mat-card-subtitle>Using 'fxLayoutGap' to create a grid-like layout
+      </mat-card-subtitle>
+      <mat-card-content class="large">
+        <div fxFlexFill>
+          <div fxFlex
+               [fxLayout]="direction + ' wrap'"
+               fxLayoutGap="10px grid"
+               style="cursor: pointer;"
+               (click)="toggleDirection()">
+            <div fxFlex="25">
+              <div class="one" fxFlexFill fxLayoutAlign="center center">
+                A
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="two" fxFlexFill fxLayoutAlign="center center">
+                B
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="three" fxFlexFill fxLayoutAlign="center center">
+                C
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="four" fxFlexFill fxLayoutAlign="center center">
+                D
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="five" fxFlexFill fxLayoutAlign="center center">
+                E
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="six" fxFlexFill fxLayoutAlign="center center">
+                F
+              </div>
+            </div>
+            <div fxFlex="25">
+              <div class="seven" fxFlexFill fxLayoutAlign="center center">
+                G
+              </div>
+            </div>
+          </div>
+        </div>
+      </mat-card-content>
+      <mat-card-footer class="bottomPad">
+        <div class="hint"></div>
+      </mat-card-footer>
+    </mat-card>
+  `
+})
+export class LayoutGapComponent {
+  direction = 'row';
+
+  toggleDirection() {
+    const next = (DIRECTIONS.indexOf(this.direction) + 1 ) % DIRECTIONS.length;
+    this.direction = DIRECTIONS[next];
+  }
+}

src/apps/demo-app/src/app/layout/layout.module.ts

@@ -18,6 +18,7 @@ import {RoutingModule} from './routing.module';
 import {
   LayoutWithDirectionComponent
 } from './layout-with-direction/layout-with-direction.component';
+import {LayoutGapComponent} from './layout-gap/layout-gap.component';
 
 @NgModule({
   imports: [
@@ -38,6 +39,7 @@ import {
     FlexOffsetValuesComponent,
     FlexAlignSelfComponent,
     LayoutWithDirectionComponent,
+    LayoutGapComponent,
   ]
 })
 export class DocsLayoutModule {}

src/lib/flex/layout-gap/layout-gap.spec.ts

@@ -13,7 +13,12 @@ import {SERVER_TOKEN, StyleUtils} from '@angular/flex-layout/core';
 
 import {FlexLayoutModule} from '../../module';
 import {customMatchers, expect} from '../../utils/testing/custom-matchers';
-import {expectEl, makeCreateTestComponent, queryFor} from '../../utils/testing/helpers';
+import {
+  expectEl,
+  expectNativeEl,
+  makeCreateTestComponent,
+  queryFor,
+} from '../../utils/testing/helpers';
 
 describe('layout-gap directive', () => {
   let fixture: ComponentFixture<any>;
@@ -151,7 +156,6 @@ describe('layout-gap directive', () => {
         // Since the layoutGap directive detects the *ngFor changes by using a MutationObserver, the
         // browser will take up some time, to actually announce the changes to the directive.
         // (Kudos to @DevVersion)
-
         nodes = queryFor(fixture, '[fxFlex]');
         expect(nodes.length).toEqual(3);
 
@@ -341,13 +345,57 @@ describe('layout-gap directive', () => {
     });
   });
 
+  describe('grid option', () => {
+    it('should add gap styles correctly', () => {
+      let template = `
+        <div fxLayoutGap='13px grid'>
+          <div fxFlex></div>
+          <div fxFlex></div>
+          <div fxFlex></div>
+        </div>
+      `;
+      createTestComponent(template);
+      fixture.detectChanges();
+
+      let nodes = queryFor(fixture, '[fxFlex]');
+      let expectedMargin = {'margin': '0px -13px -13px 0px'};
+      let expectedPadding = {'padding': '0px 13px 13px 0px'};
+      expect(nodes.length).toEqual(3);
+      expectEl(nodes[0]).toHaveStyle(expectedPadding, styler);
+      expectEl(nodes[1]).toHaveStyle(expectedPadding, styler);
+      expectEl(nodes[2]).toHaveStyle(expectedPadding, styler);
+      expectNativeEl(fixture).toHaveStyle(expectedMargin, styler);
+    });
+
+    it('should add gap styles correctly for rtl', () => {
+      fakeDocument.body.dir = 'rtl';
+      let template = `
+        <div fxLayoutGap='13px grid'>
+          <div fxFlex></div>
+          <div fxFlex></div>
+          <div fxFlex></div>
+        </div>
+      `;
+      createTestComponent(template);
+      fixture.detectChanges();
+
+      let nodes = queryFor(fixture, '[fxFlex]');
+      let expectedMargin = {'margin': '0px 0px -13px -13px'};
+      let expectedPadding = {'padding': '0px 0px 13px 13px'};
+      expect(nodes.length).toEqual(3);
+      expectEl(nodes[0]).toHaveStyle(expectedPadding, styler);
+      expectEl(nodes[1]).toHaveStyle(expectedPadding, styler);
+      expectEl(nodes[2]).toHaveStyle(expectedPadding, styler);
+      expectNativeEl(fixture).toHaveStyle(expectedMargin, styler);
+    });
+  });
+
 });
 
 
 // *****************************************************************
 // Template Component
 // *****************************************************************
-
 @Component({
   selector: 'test-layout',
   template: `<span>PlaceHolder Template HTML</span>`
@@ -363,5 +411,3 @@ class TestLayoutGapComponent implements OnInit {
   ngOnInit() {
   }
 }
-
-

src/lib/flex/layout-gap/layout-gap.ts

@@ -18,7 +18,13 @@ import {
   NgZone,
 } from '@angular/core';
 import {Directionality} from '@angular/cdk/bidi';
-import {BaseFxDirective, MediaChange, MediaMonitor, StyleUtils} from '@angular/flex-layout/core';
+import {
+  BaseFxDirective,
+  MediaChange,
+  MediaMonitor,
+  StyleDefinition,
+  StyleUtils
+} from '@angular/flex-layout/core';
 import {Subscription} from 'rxjs/Subscription';
 
 import {Layout, LayoutDirective} from '../layout/layout';
@@ -155,9 +161,9 @@ export class LayoutGapDirective extends BaseFxDirective
    *
    */
   protected _updateWithValue(value?: string) {
-    value = value || this._queryInput('gap') || '0';
+    let gapValue = value || this._queryInput('gap') || '0';
     if (this._mqActivation) {
-      value = this._mqActivation.activatedInput;
+      gapValue = this._mqActivation.activatedInput;
     }
 
     // Gather all non-hidden Element nodes
@@ -174,15 +180,56 @@ export class LayoutGapDirective extends BaseFxDirective
       });
 
     if (items.length > 0) {
-      const lastItem = items.pop();
+      if (gapValue.endsWith(GRID_SPECIFIER)) {
+        gapValue = gapValue.substring(0, gapValue.indexOf(GRID_SPECIFIER));
+        // For each `element` children, set the padding
+        this._applyStyleToElements(this._buildGridPadding(gapValue), items);
+
+        // Add the margin to the host element
+        this._applyStyleToElement(this._buildGridMargin(gapValue));
+      } else {
+        const lastItem = items.pop();
+
+        // For each `element` children EXCEPT the last,
+        // set the margin right/bottom styles...
+        this._applyStyleToElements(this._buildCSS(gapValue), items);
+
+        // Clear all gaps for all visible elements
+        this._applyStyleToElements(this._buildCSS(), [lastItem]);
+      }
+    }
+  }
+
+  /**
+   *
+   */
+  private _buildGridPadding(value: string): StyleDefinition {
+    let paddingTop = '0px', paddingRight = '0px', paddingBottom = value, paddingLeft = '0px';
 
-      // For each `element` children EXCEPT the last,
-      // set the margin right/bottom styles...
-      this._applyStyleToElements(this._buildCSS(value), items);
+    if (this._directionality.value === 'rtl') {
+      paddingLeft = value;
+    } else {
+      paddingRight = value;
+    }
+
+    return {'padding': `${paddingTop} ${paddingRight} ${paddingBottom} ${paddingLeft}`};
+  }
 
-      // Clear all gaps for all visible elements
-      this._applyStyleToElements(this._buildCSS(), [lastItem]);
+  /**
+   * Prepare margin CSS, remove any previous explicitly
+   * assigned margin assignments
+   * Note: this will not work with calc values (negative calc values are invalid)
+   */
+  private _buildGridMargin(value: string): StyleDefinition {
+    let marginTop = '0px', marginRight = '0px', marginBottom = '-' + value, marginLeft = '0px';
+
+    if (this._directionality.value === 'rtl') {
+      marginLeft = '-' + value;
+    } else {
+      marginRight = '-' + value;
     }
+
+    return {'margin': `${marginTop} ${marginRight} ${marginBottom} ${marginLeft}`};
   }
 
   /**
@@ -212,5 +259,6 @@ export class LayoutGapDirective extends BaseFxDirective
 
     return margins;
   }
-
 }
+
+const GRID_SPECIFIER = ' grid';