Prototype flows with HotSpot and Artboard ids (#436)

* implement viewport preset prop for <Artboard>

* revert API.md table formatting

* implement HotSpot component with artboard stable seeds

* add Artboard isHome prop for prototype flow

* add prototype docs for HotSpot and Artboard

* add HotSpot to docs contents

* fix HotSpot propTypes

* Port HotSpot to View & get objectID from index

* remove redundant HotSpot from docs

* fix generateID index

* revert Artboard id prop & re-add generateID hardcoded

* clean up prototype docs

Author: macintoshhelper

__tests__/jest/jsonUtils/models.js

@@ -11,6 +11,12 @@ describe('generateID', () => {
   it('is unique', () => {
     expect(generateID()).not.toBe(generateID());
   });
+  it('seed generates different ID', () => {
+    expect(generateID('test')).not.toBe(generateID('test'));
+  });
+  it('hardcoded seed generates same ID', () => {
+    expect(generateID('test', true)).toBe(generateID('test', true));
+  });
 });
 
 const BLACK = {

docs/API.md

@@ -144,6 +144,7 @@ Wrapper for Sketch's Artboards. Requires a [`<Page>`](#page) component as a pare
 | `children` | `Node`                      |         |                                                        |
 | `style`    | [`Style`](/docs/styling.md) |         |                                                        |
 | `viewport` | `Viewport`                  |         | Object: { name: string, width: number, height: number} |
+| `isHome`   | `Boolean`                   |         | Is prototype home screen if true                       |
 
 #### Examples
 
@@ -328,8 +329,11 @@ View primitives
 | `name`     | `String`                    |         | The name to be displayed in the Sketch Layer List |
 | `children` | `Node`                      |         |                                                   |
 | `style`    | [`Style`](/docs/styling.md) |         |                                                   |
+| `flow`     | `Flow`                      |         | Object: { target: string, targetId: string, animationType: string } |
 
-#### Example
+#### Examples
+
+**Example with children**
 
 ```js
 <View
@@ -346,6 +350,37 @@ View primitives
 </View>
 ```
 
+**Example using `flow` prop for prototyping destination**
+
+```js
+<Document>
+  <Artboard name="Home">
+    <View
+      name="Menu Button"
+      style={{
+        height: 100,
+        backgroundColor: '#01ffae',
+      }}
+      flow={{
+        target: 'menu' // From <Artboard name" or can be "back"
+        // targetId: uuid (can be used to reference existing artboards/uuids)
+        // animationType: string (constants can be used from require('sketch') API, or hardcoded)
+      }}
+    >
+      <Text>Open menu!</Text>
+    </View>
+  </Artboard>
+  <Artboard name="Menu">
+    <View
+      name="Go back"
+      flow={{ target: 'back' }} /* "back" used instead of <Artboard> id */
+    >
+      <Text>Go back!</Text>
+    </View>
+  </Artboard>
+</Document>
+```
+
 ## Platform
 
 ### `OS`

src/components/Artboard.js

@@ -17,6 +17,7 @@ export default class Artboard extends React.Component {
     // TODO(lmr): do some nice warning stuff like RN does
     style: or([PropTypes.shape(ViewStylePropTypes), PropTypes.number]),
     name: PropTypes.string,
+    isHome: PropTypes.bool,
     children: PropTypes.node,
     viewport: PropTypes.shape(ViewportPropTypes),
   };
@@ -31,6 +32,7 @@ export default class Artboard extends React.Component {
         style={StyleSheet.flatten(this.props.style)}
         name={this.props.name}
         viewport={this.props.viewport}
+        isHome={this.props.isHome}
       >
         {this.props.children}
       </artboard>

src/components/View.js

@@ -19,6 +19,11 @@ export const ViewPropTypes = {
       ...ShadowsPropTypes,
     }),
   ),
+  flow: PropTypes.shape({
+    targetId: PropTypes.string,
+    target: PropTypes.string,
+    animationType: PropTypes.string,
+  }),
   children: PropTypes.node,
 };
 
@@ -37,6 +42,7 @@ export default class View extends React.Component {
         style={StyleSheet.flatten(this.props.style)}
         resizingConstraint={this.props.resizingConstraint}
         shadows={this.props.shadows}
+        flow={this.props.flow}
       >
         {this.props.children}
       </view>

src/jsonUtils/hotspotLayer.js

@@ -0,0 +1,45 @@
+// @flow
+import type { SJObjectId } from 'sketchapp-json-flow-types';
+
+import { generateID } from './models';
+
+type SJFlow = {
+  _class: 'MSImmutableFlowConnection',
+  animationType: number,
+  destinationArtboardID?: SJObjectId | 'back',
+};
+
+const animationTypes = {
+  none: -1,
+  slideFromRight: 0,
+  slideFromLeft: 1,
+  slideFromBottom: 2,
+  slideFromTop: 3,
+};
+
+const BackTarget = 'back';
+
+const getArtboard = target => {
+  if (target === BackTarget) {
+    return BackTarget;
+  }
+  return generateID(`artboard:${target}`, true);
+};
+
+const hotspotLayer = ({
+  targetId,
+  target,
+  animationType,
+}: {
+  targetId?: string,
+  target?: string,
+  animationType?: string,
+}): { flow: SJFlow } => ({
+  flow: {
+    _class: 'MSImmutableFlowConnection',
+    animationType: (animationType && animationTypes[animationType]) || -1,
+    destinationArtboardID: target ? getArtboard(target) : targetId,
+  },
+});
+
+export default hotspotLayer;

src/jsonUtils/models.js

@@ -57,16 +57,18 @@ function generateIdNumber() {
 // Keep track of previous seeds
 const previousSeeds = {};
 
-export function generateID(seed?: ?string): string {
-  let _seed: ?string;
+export function generateID(seed?: ?string, hardcoded?: boolean): string {
+  let _seed: ?string = seed;
 
   if (seed) {
     if (!previousSeeds[seed]) {
       previousSeeds[seed] = 0;
     }
     previousSeeds[seed] += 1;
 
-    _seed = `${seed}${previousSeeds[seed]}`;
+    if (!hardcoded) {
+      _seed = `${seed}${previousSeeds[seed]}`;
+    }
   }
 
   return e7(_seed);

src/renderers/ArtboardRenderer.js

@@ -18,7 +18,7 @@ export default class ArtboardRenderer extends SketchRenderer {
 
     return {
       _class: 'artboard',
-      do_objectID: generateID(),
+      do_objectID: generateID(`artboard:${props.name}`, true),
       frame: makeRect(layout.left, layout.top, layout.width, layout.height),
       // "layerListExpandedType": 0,
       name: props.name || 'Artboard',
@@ -27,6 +27,7 @@ export default class ArtboardRenderer extends SketchRenderer {
       isVisible: true,
       backgroundColor: color || makeColorFromCSS('white'),
       hasBackgroundColor: color !== undefined,
+      ...(props.isHome && { isFlowHome: true }),
       ...(props.viewport && {
         presetDictionary: {
           allowResizedMatching: 0,

src/renderers/SketchRenderer.js

@@ -1,5 +1,6 @@
 // @flow
 import layerGroup from '../jsonUtils/layerGroup';
+import hotspotLayer from '../jsonUtils/hotspotLayer';
 import type { LayoutInfo, ViewStyle, TextStyle, TreeNode } from '../types';
 import processTransform from '../utils/processTransform';
 
@@ -31,6 +32,7 @@ export default class SketchRenderer {
       ),
       name: props.name || this.getDefaultGroupName(props),
       ...transform,
+      ...(props.flow && hotspotLayer(props.flow)),
     };
   }