add basic Surface examples

docs/src/routes/documentation/Surface/Example1.js

@@ -0,0 +1,32 @@
+// @flow weak
+
+import React from 'react';
+import Surface from 'resonance/Surface';
+
+/**
+ * A simple example of `Surface` component.
+ * By adopting the the convention of defining view and trbl props
+ * it makes it easier to reason about the placement of child elements.
+ * Note how the rect element has no translation and is drawn with the correct margins around it
+ */
+const color = 'rgba(0,0,0,0.3)';
+
+const view = [1000, 250];      // view [width, height] fed to SVG viewbox attribute
+const trbl = [10, 10, 10, 100]; // Margins [top, right, bottom, left] for the SVG
+
+const dims = [ // The usable dimensions.
+  view[0] - trbl[1] - trbl[3],
+  view[1] - trbl[0] - trbl[2],
+];
+
+const Exmaple1 = () => (
+  <Surface
+    view={view}
+    trbl={trbl}
+    style={{ backgroundColor: color }}
+  >
+    <rect width={dims[0]} height={dims[1]} fill={color} />
+  </Surface>
+);
+
+export default Exmaple1;

docs/src/routes/documentation/Surface/Example2.js

@@ -0,0 +1,40 @@
+// @flow weak
+
+import React from 'react';
+import Surface from 'resonance/Surface';
+
+/**
+ * This example shows how surfaces will conform to their containers
+ * NOTE: Bootstrap grid CSS is loaded on this page and are used to define the layout below
+ */
+const color = 'rgba(0,0,0,0.3)';
+
+const view = [1000, 250];      // view [width, height] fed to SVG viewbox attribute
+const trbl = [10, 10, 10, 100]; // Margins [top, right, bottom, left] for the SVG
+
+const dims = [ // The usable dimensions.
+  view[0] - trbl[1] - trbl[3],
+  view[1] - trbl[0] - trbl[2],
+];
+
+const GreySurface = () => (
+  <Surface
+    view={view}
+    trbl={trbl}
+    style={{ backgroundColor: color }}
+  >
+    <rect width={dims[0]} height={dims[1]} fill={color} />
+  </Surface>
+);
+
+const Example2 = () => (
+  <div className="row">
+    {[1, 2, 3, 4].map((d) => (
+      <div key={d} className="col-md-3 col-sm-6" style={{ padding: 2 }}>
+        <GreySurface />
+      </div>
+    ))}
+  </div>
+);
+
+export default Example2;

docs/src/routes/documentation/Surface/README.md

@@ -1,3 +1,22 @@
 ## Surface
 
-A basic SVG container for visualizations.
+A basic svg container for visualizations.
+It's completely optional to use the ***Surface*** as the other components do not depend on it.
+Using the ***Surface*** component, the svg will scale to fit its container as the window size adjusts but maintain a constant aspect ratio (unless you update the view prop).
+This is an alternative to using JavaScript listeners to update the svg's width and height in response to resize events.
+Changing the width and height of the svg via JavaScript can be inefficient for complex visualizations.
+Changing the aspect ratio also leads to distorted, inconsistent views of data at different window sizes.
+There are, of course, pros and cons to the different methods and in some cases where using JavaScript to resize the svg will be appropriate.
+
+### A couple of things to note:
+
+1. The outermost element is a div (not an svg element) with styles to make the contained svg scale correctly in most browsers.
+You can augment the outer div styles by sending a style object. 
+
+2. The div has an svg element as its only child. The svg, in turn, contains a single g element as it's child.
+
+3. The g element is translated into position automatically for you according to the margins you define in your trbl prop. See the examples below.
+
+4. The child elements of the ***Surface*** will be placed inside of the translated g element.
+This makes it easier to adjust your visualization for titles, axes, notes, etc (just adjust the trbl prop).
+You can see how this works in the examples below.

docs/src/routes/documentation/Surface/index.js

@@ -2,56 +2,37 @@
 
 import React, { Component, PropTypes } from 'react';
 import Title from 'react-title-component';
-// import CodeExample from 'docs/src/components/CodeExample';
+import CodeExample from 'docs/src/components/CodeExample';
 import MarkdownElement from 'docs/src/components/MarkdownElement';
 import PropTypeDescription from 'docs/src/components/PropTypeDescription';
 
-// import AppBarExampleIcon from './ExampleIcon';
-// import AppBarExampleIconButton from './ExampleIconButton';
-// import AppBarExampleComposition from './ExampleComposition';
+import Example1 from './Example1';
+import Example2 from './Example2';
 
 class SurfaceDocs extends Component {
   static propTypes = {
     route: PropTypes.object.isRequired,
   }
 
-  // render() {
-  //   const { route: { docContext, srcContext } } = this.props;
-
-  //   return (
-  //     <div>
-  //       <Title render={(previousTitle) => `Surface - ${previousTitle}`} />
-  //       <MarkdownElement text={docContext('./Surface/README.md')} />
-  //       <CodeExample
-  //         code={docContext('./Surface/ExampleIcon')}
-  //         title="Simple example"
-  //       >
-  //         <AppBarExampleIcon />
-  //       </CodeExample>
-  //       <CodeExample
-  //         code={docContext('./Surface/ExampleIconButton')}
-  //         title="Buttons example"
-  //       >
-  //         <AppBarExampleIconButton />
-  //       </CodeExample>
-  //       <CodeExample
-  //         code={docContext('./Surface/ExampleComposition')}
-  //         title="Composition example"
-  //       >
-  //         <AppBarExampleComposition />
-  //       </CodeExample>
-  //       <PropTypeDescription code={srcContext('./Surface/Surface')} />
-  //     </div>
-  //   );
-  // }
-
   render() {
     const { route: { docContext, srcContext } } = this.props;
 
     return (
       <div>
         <Title render={(previousTitle) => `Surface - ${previousTitle}`} />
         <MarkdownElement text={docContext('./Surface/README.md')} />
+        <CodeExample
+          code={docContext('./Surface/Example1')}
+          title="Example 1: Basic Surface"
+        >
+          <Example1 />
+        </CodeExample>
+        <CodeExample
+          code={docContext('./Surface/Example2')}
+          title="Example 2: Multiple Surfaces"
+        >
+          <Example2 />
+        </CodeExample>
         <PropTypeDescription code={srcContext('./Surface/Surface')} />
       </div>
     );