First pass docs & add gitbook

.eslintignore

@@ -2,4 +2,5 @@
 **/react-example.sketchplugin/**
 **/node_modules/**
 **/flow-typed/**
+**/_book/**
 webpack.config*

.gitignore

@@ -3,3 +3,4 @@
 node_modules
 lib
 react-example.sketchplugin
+_book

CHANGELOG.md

@@ -1,2 +1,4 @@
-## 0.1.0 (Nov 28, 2016)
-Initial push
+# Change Log
+
+This project adheres to [Semantic Versioning](http://semver.org/).
+Every release, along with the migration instructions, is documented on the Github [Releases](https://github.com/jongold/react-sketchapp/releases) page.

README.md

@@ -6,97 +6,27 @@
 [![Build Status](https://img.shields.io/travis/jongold/react-sketchapp.svg)](https://travis-ci.org/jongold/react-sketchapp)
 [![npm](https://img.shields.io/npm/v/react-sketchapp.svg)](https://www.npmjs.com/package/react-sketchapp)
 
-Declarative bridge to Sketch.app.
+- 🦄 Render React components to Sketch.app!
+- 🦄 Use flexbox for layout!
+- 🦄 Build Sketch documents with real data!
+- 🦄 Share styles & components between platforms!
 
-WIP; not ready for public consumption yet!
+## Motivation
+`react-sketchapp` evolved out of our need to generate high-quality, consistent Sketch assets for our design system at Airbnb. Wrapping Sketch’s imperative API is a pragmatic solution for consistent & predictable rendering. By using the same component API as `react-native`—`<View />`, `<Text />`, `<Image />` instead of `<Rect />`, `<Oval />` etc—we can use the same layout algorithms and components across multiple platforms.
+
+Existing plugins try to go from Sketch to the browser (CSS, HTML, sometimes even components) — for our use case this is the wrong model. By inverting the system we can keep our source of truth in code, and treat Sketch as a pure render function.
 
 ## Running example scripts
 Make sure Sketch automatically reloads plugins:
-```sh
+```bash
 defaults write ~/Library/Preferences/com.bohemiancoding.sketch3.plist AlwaysReloadScript -bool YES
 ```
 
 Clone & build the repo, and symlink the examples:
-```sh
-git clone git@github.com:jongold/react-sketchapp.git
-cd react-sketchapp
-npm install && npm run watch:plugin
+```bash
+git clone git@github.com:jongold/react-sketchapp.git && cd react-sketchapp
+npm install && npm run build:plugin
 ./symlink-plugin.sh
 ```
 
-Open Sketch; examples will be in `Plugins -> react-example`.
-
-## Using react-sketchapp
-Check out:
-```
-webpack.config.js
-example-plugin/
-  *.js (raw sources)
-react-example.sketchplugin
-  Contents/
-    Sketch/
-      manifest.json
-      *.js (compiled code)
-```
-
-You'll want to create a new repo, create a similar build process to ^^^, and implement your handler ~= this:
-
-```jsx
-import { render, Artboard, View, Text } from 'react-sketchapp';
-
-const Document = () => (
-  <Artboard>
-    <View>
-      <View
-        style={{
-          height: 10,
-          width: 10,
-          backgroundColor: '#333',
-        }}
-      />
-      <Text
-        style={{
-          fontSize: 24,
-          fontFamily: 'FontFoo-PostscriptName',
-          //etc
-        }}
-        children='yoooo'
-      />
-    </View>
-  </Artboard>
-);
-
-const onRun = (context) => {
-  render(<Document />, context);
-};
-```
-
-## Documentation
-WIP, sorry. `<View />` & `<Text />` mirror their [`react-native`](https://github.com/facebook/react-native) /
-[`react-primitives`](https://github.com/lelandrichardson/react-primitives)
-counterparts - have fun with full flexbox layout.
-
-## Further Reading & inspiration
-### React Renderers
-- [Dustan Kasten - tiny-react-renderer](https://github.com/iamdustan/tiny-react-renderer)
-
-- [Dustan Kasten - react-hardware](https://github.com/iamdustan/react-hardware)
-
-- [Dustan Kasten - React renderer directory](http://iamdustan.com/react-renderers/)
-
-- [Gosha Arinich - Making custom renderers for React](http://goshakkk.name/react-custom-renderers/)
-
-- [Flipboard - react-canvas](https://github.com/Flipboard/react-canvas)
-
-- 🎥 [Jafar Husain — Beyond The DOM](https://www.youtube.com/watch?v=eNC0mRYGWgc)
-
-### Sketch Plugins
-- Creating custom UIs https://github.com/romannurik/sketch-nibuitemplateplugin
-
-- Interacting with binaries https://github.com/abynim/Sketch-PluginHelper
-
-- CocoaScript reference https://sketchplugindev.james.ooo/interacting-with-objective-c-classes-in-cocoascript-68be7f39616f#.e2fndxvpp
-
-- Fluid for Sketch - provides a means to create constraint-based designs. Shows custom UI and interacts with a framework https://github.com/matt-curtis/Fluid-for-Sketch https://github.com/matt-curtis/Sketch-Plugin-Framework
-
-- Create shapes from props https://github.com/elliotekj/specify
+Open Sketch; examples will be in `Plugins → react-example`.

SUMMARY.md

@@ -0,0 +1 @@
+docs/README.md

book.json

@@ -0,0 +1,22 @@
+{
+  "gitbook": ">= 3.2.1",
+  "title": "react-sketchapp",
+  "plugins": [
+    "edit-link",
+    "prism",
+    "-highlight",
+    "github",
+    "-search",
+    "codeblock-disable-glossary",
+    "anchorjs"
+  ],
+  "pluginsConfig": {
+    "edit-link": {
+      "base": "https://github.com/jongold/react-sketchapp/tree/master",
+      "label": "Edit This Page"
+    },
+    "github": {
+      "url": "https://github.com/jongold/react-sketchapp/"
+    }
+  }
+}

docs/README.md

@@ -0,0 +1,14 @@
+## Table of Contents
+
+* [Introduction](/README.md)
+* [Usage](/docs/usage.md)
+* [Styling](/docs/styling.md)
+* [Universal Rendering](/docs/universal-rendering.md)
+* [API Reference](/docs/api/README.md)
+  * [render](/docs/api/render.md)
+  * [Artboard](/docs/api/Artboard.md)
+  * [Platform](/docs/api/Platform.md)
+  * [StyleSheet](/docs/api/Stylesheet.md)
+  * [Text](/docs/api/Text.md)
+  * [View](/docs/api/View.md)
+* [Troubleshooting](/docs/troubleshooting.md)

docs/api/Artboard.md

@@ -0,0 +1,16 @@
+# `Artboard`
+
+Artboard is a wrapper for Sketch artboards.
+
+#### Props
+- `name` _(String)_: The component name
+- `style` _(Style)_: See [styling](/docs/styling.md)
+
+
+#### Example
+```jsx
+const Document = () =>
+  <Artboard>
+    <Text>Hello world!</Text>
+  </Artboard>
+```

docs/api/Platform.md

@@ -0,0 +1,6 @@
+# `Platform`
+
+#### Props
+- `OS` _(String)_
+- `Version` _(Number)_
+- `select` _(obj => obj)

docs/api/README.md

@@ -0,0 +1,9 @@
+# API Reference
+
+### Top-Level Exports
+- [render(element, context)](render.md)
+- [Artboard](Artboard.md)
+- [Platform](Platform.md)
+- [StyleSheet](Stylesheet.md)
+- [Text](Text.md)
+- [View](View.md)

docs/api/StyleSheet.md

@@ -0,0 +1,3 @@
+# StyleSheet
+
+WIP

docs/api/Text.md

@@ -0,0 +1,11 @@
+# Text
+
+WIP
+
+**Examples**
+
+```jsx
+<Text name='Foo' style={style}>
+  Hello World!
+</Text>
+```

docs/api/View.md

@@ -0,0 +1,11 @@
+# View
+
+WIP
+
+**Examples**
+
+```jsx
+<View name='Foo' style={style}>
+  <Text />
+</View>
+```

docs/api/render.md

@@ -0,0 +1,15 @@
+# render
+
+Render a React element using a provided SketchContext.
+
+#### Parameters
+- `element` _(React$Element<any>)_
+- `context` _(SketchContext)_
+
+**Examples**
+
+```jsx
+const onRun = (context) => {
+  render(<View />, context);
+}
+```

docs/styling.md

@@ -0,0 +1,147 @@
+# Styling
+
+Components use the same flexbox algorithm as `react-native`!
+
+#### Layout Styles
+```javascript
+export type ViewStyle = {
+  // shadowColor: Color,
+  // shadowOffset: { width: number, height: number },
+  // shadowOpacity: number,
+  // shadowRadius: number,
+  width: number,
+  height: number,
+  top: number,
+  left: number,
+  right: number,
+  bottom: number,
+  minWidth: number,
+  maxWidth: number,
+  minHeight: number,
+  maxHeight: number,
+  margin: number,
+  marginVertical: number,
+  marginHorizontal: number,
+  marginTop: number,
+  marginBottom: number,
+  marginLeft: number,
+  marginRight: number,
+  padding: number,
+  paddingVertical: number,
+  paddingHorizontal: number,
+  paddingTop: number,
+  paddingBottom: number,
+  paddingLeft: number,
+  paddingRight: number,
+  borderWidth: number,
+  borderTopWidth: number,
+  borderRightWidth: number,
+  borderBottomWidth: number,
+  borderLeftWidth: number,
+  position: 'absolute' | 'relative',
+  flexDirection: 'row' | 'row-reverse' | 'column' | 'column-reverse',
+  flexWrap: 'wrap' | 'nowrap',
+  justifyContent: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around',
+  alignItems: 'flex-start' | 'flex-end' | 'center' | 'stretch',
+  alignSelf: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch',
+  // overflow: 'visible' | 'hidden' | 'scroll',
+  flex: number,
+  flexGrow: number,
+  flexShrink: number,
+  flexBasis: number,
+  // aspectRatio: number,
+  zIndex: number,
+  // backfaceVisibility: 'visible' | 'hidden',
+  backgroundColor: Color,
+  borderColor: Color,
+  borderTopColor: Color,
+  borderRightColor: Color,
+  borderBottomColor: Color,
+  borderLeftColor: Color,
+  borderRadius: number,
+  borderTopLeftRadius: number,
+  borderTopRightRadius: number,
+  borderBottomLeftRadius: number,
+  borderBottomRightRadius: number,
+  borderStyle: 'solid' | 'dotted' | 'dashed',
+  borderWidth: number,
+  borderTopWidth: number,
+  borderRightWidth: number,
+  borderBottomWidth: number,
+  borderLeftWidth: number,
+  opacity: number,
+};
+```
+
+#### Type Styles
+```javascript
+export type TextStyle = {
+  color: Color,
+  fontFamily: string,
+  fontSize: number,
+  fontStyle: 'normal' | 'italic',
+  fontWeight: string,
+  // textShadowOffset: { width: number, height: number },
+  // textShadowRadius: number,
+  // textShadowColor: Color,
+  letterSpacing: number,
+  lineHeight: number,
+  textAlign: 'auto' | 'left' | 'right' | 'center' | 'justify',
+  // writingDirection: 'auto' | 'ltr' | 'rtl',
+};
+```
+
+Styles can be passed to components as plain objects, or via [`StyleSheet`](/docs/api/StyleSheet.md).
+
+```
+import { View, StyleSheet } from 'react-sketchapp';
+
+// inline props
+<View
+  style={{
+    backgroundColor: 'hotPink',
+    width: 300,
+  }}
+/>
+
+// plain JS object
+const style = {
+  backgroundColor: 'hotPink',
+  width: 300,
+}
+
+<View style={style} />
+
+// StyleSheet
+const styles = StyleSheet.create({
+  foo: {
+    backgroundColor: 'hotPink',
+    width: 300,
+  }
+})
+
+<View style={styles.foo} />
+<View style={[styles.foo, styles.bar]} />
+```
+
+You can use variables in your styles just like a standard React application:
+```javascript
+const colors = {
+  Haus: '#F3F4F4',
+  Night: '#333',
+  Sur: '#96DBE4',
+  Peach: '#EFADA0',
+  Pear: '#93DAAB',
+};
+
+<View>
+  { Object.keys(colors).map(name => {
+    <View
+      style={{
+        flex: 1,
+        backgroundColor: colors[name],
+      }}
+    />
+  }) }
+</View>
+```