Guided Tours: Add docs for our API #10007

marekhrabe · 2016-12-13T15:06:59Z

Our API consists mainly of JSX components that you compose to create a tour. This PR should add explanations for their usage.

matticbot · 2016-12-13T15:07:06Z

Test live: https://calypso.live/?branch=add/gt-component-docs

mcsf · 2016-12-14T11:28:06Z

As discussed in Slack, +1 to splitting this off into its own docs/API.md file or similar.

Meanwhile, my other observation, once that happens, would be to separate the API description into two sections: layout components and flow-control components. Although Tour and Step are arguably very special in that they do both, I would place them under layout, like so:

layout: Tour, Step, ButtonRow, Link
flow control: Next, Quit, Continue

Oh, and I would choose a more deliberate sorting of the items, like the one I suggested above, than something alphabetical. In this particular case, I think it creates an easier-to-follow sequence, from broad to narrow (Tour → Step → Row), from simple to flexible (Next → Continue).

mcsf

Looks good so far! Added a few comments. The mini examples are very useful, IMO

mcsf · 2016-12-16T16:19:34Z

client/layout/guided-tours/docs/API.md

@@ -0,0 +1,162 @@
+# Guided Tours API
+
+Guided Tours are declared as a tree of JSX components.


Since

JSX is just syntactic sugar;

I believe these are technically elements (as in: Foo is a component, <Foo /> is an element);

I think we could rephrase as

-Guided Tours are declared as a tree of JSX components. +Guided Tours are declared in JSX as a tree of elements.

mcsf · 2016-12-16T16:41:43Z

client/layout/guided-tours/docs/API.md

+### Props
+
+* `name`: (string) Unique identifier of the step.
+* `target`: (string, optional) Target which this step belongs to and will be used for positioning. This prop is value is used to look up according `[data-tip-target]` in DOM. If omitted, `<body>` will be used as target. TODO: mention querySelector hack?, is body really default target?


querySelector hack

Even though it was intended as a secondary mechanism, we do use it a bit and has a few interesting strengths, like in when .some-container .some-state-like-is-valid .my-target. We should mention it.

<body> will be used

Well, in a way. positioning will grab body.getBoundingClientRect() in a few places if no target is found, but I wouldn't say that body is a "default target". Failing to provide a target will mess up positioning with most placement methods, unless they're meant for that.

Oh, and the second sentence has a typo or omission somewhere — maybe s/is value/'s value/?

mcsf · 2016-12-16T16:42:19Z

client/layout/guided-tours/docs/API.md

+* `name`: (string) Unique identifier of the step.
+* `target`: (string, optional) Target which this step belongs to and will be used for positioning. This prop is value is used to look up according `[data-tip-target]` in DOM. If omitted, `<body>` will be used as target. TODO: mention querySelector hack?, is body really default target?
+* `placement`: (string, optional) Placement. Possible values: 'below', 'above', 'beside', 'center', 'middle', 'right'
+* `arrow`: (string, optional) If defined, step will get arrow pointing to a direction. Available: 'top-left', 'top-center', 'top-right',


Should we explain what they are? The names are kind of meaningless. Same question for placement

Better yet, have a mini-gallery at the end of this paragraph with captions showing the arrows? :) Could be doable by tweaking props directly via React dev tools.

mcsf · 2016-12-16T16:45:37Z

client/layout/guided-tours/docs/API.md

+* `placement`: (string, optional) Placement. Possible values: 'below', 'above', 'beside', 'center', 'middle', 'right'
+* `arrow`: (string, optional) If defined, step will get arrow pointing to a direction. Available: 'top-left', 'top-center', 'top-right',
+'right-top', 'right-middle', 'right-bottom', 'bottom-left', 'bottom-center', 'bottom-right', 'left-top', 'left-middle', 'left-bottom'
+* `style`: (object, optional) Will be used as step's inline style.


I would add a word of advice, like:

use sparingly;

avoid changing the look and feel of Guided Tours;

useful for minor positioning adjustments, z-index, etc.

mcsf · 2016-12-16T16:47:29Z

client/layout/guided-tours/docs/API.md

+
+Note that all text content needs to be wrapped in `<p>` so it gets proper styling.
+
+This is just a quick and not very useful tour. You can see more examples in [TUTORIAL.md](TUTORIAL.md) or by exploring existing tours in client/layout/guided-tours/tours.


I'd make this shorter, skip the first sentence and open with For more comprehensive examples, …

mcsf · 2016-12-16T16:51:26Z

client/layout/guided-tours/docs/API.md

+* `hidden`: (bool, optional) If true, this will not render anything in Step, while functionality remains.
+* `icon`: (string, optional) Name of Gridicon to show in custom message.
+* `when`: (function, optional) Redux selector. Once it evaluates to true, tour will advance to `step`.
+


Missing prop is children. It's good to make it clear that it is possible to use children, but also (importantly) that it is not needed, as we have good defaults — with and without icon

mcsf · 2016-12-16T16:52:04Z

client/layout/guided-tours/docs/API.md

+- text
+- text + props.icon
+- custom content
+


With no introduction, I find this enumeration confusing

mcsf · 2016-12-16T16:54:15Z

client/layout/guided-tours/docs/API.md

+// continue when user clicks DOM element with html attribute `data-tip-target="my-sites"`
+<Continue step="next-step" click target="my-sites" />
+// continue when Redux selector evaluates to true (in this case after user opens preview)
+<Continue step="next-step" when={ isPreviewShowing } />


Not sure what the place to say this is, but authors should be aware that when will only work if something triggers a re-render of the step and that the proper way to set this up is to add the relevant action types to actionLog's whitelist.

mcsf · 2016-12-16T16:55:54Z

client/layout/guided-tours/docs/API.md

+// with default label
+<Next step="next-step" />
+// or with a custom one
+<Next step="next-step">Custom Label</Next>`


Add translate( )

Same for Quit

lsinger · 2016-12-23T16:33:09Z

client/layout/guided-tours/docs/API.md

+
+## All-in example
+
+Before we go into full details, let's look at this example. It includes most possible things you can use.


Make sure to say somewhere it's an example for a Step, and what a Step is. I first thought OK, I'll now get to see an example of a full tour.

lsinger · 2016-12-23T16:33:40Z

client/layout/guided-tours/docs/API.md

+
+## Tour
+
+Tour is a React component that declares the top-level of a tour. It defines conditions for starting a tour and contains `<Step>` elements as children.


Tour doesn't appear in the example above. Again, somewhat confusing.

lsinger · 2016-12-23T16:36:49Z

client/layout/guided-tours/docs/API.md

+
+## Step
+
+Step is a React component that defines a single Step of a tour. It is represented as dark box on top of Calypso UI. Step can be positioned in many ways in relation to any DOM node in Calypso that is marked with `[data-tip-target]` attribute.


target also accepts a CSS selector, we'll then use the first match.

ah, you say it below. maybe remove implementation details here and just say "DOM node in Calypso".

It's mentioned in the prop list just few lines below. Should it also be here?

see my second comment. :)

I'm still going through it, you know. :)

lsinger · 2016-12-23T16:37:24Z

client/layout/guided-tours/docs/API.md

+
+### Props
+
+* `name`: (string) Unique identifier of the step.


, used for ... (next)

also, init and finish are magic step names I think.

had no idea, thanks! btw: what if the tour has only one step? is it init?

it seems like the only magical name is init, isn't it? finish is not detected anywhere as far as I'm looking right

didn't I reply to this before? weird. in any case, you're right. finish was used previously for styling, but isn't used anymore.

lsinger · 2016-12-23T16:40:32Z

client/layout/guided-tours/docs/API.md

+### Props
+
+* `name`: (string) Unique identifier of the step.
+* `target`: (string, optional) Target which this step belongs to and will be used for positioning. Value of this prop is used to look up according `[data-tip-target]` in DOM. If you start this value with `.` (dot), it will be evaluated as a query selector, so you can select elements that have no `[data-tip-target]` defined.


also works as a selector if a space is in there. maybe add # to the check. the . is just an indicator for "hey, classname selector".

i.e. it's passed along as is. the . isn't removed.

lsinger · 2016-12-23T16:43:44Z

client/layout/guided-tours/docs/API.md

+### Props
+
+* `name`: (string) Unique identifier of the step, used for addressing a step from `Next` or `Continue`.
+* `target`: (string, optional) Target which this step belongs to and will be used for positioning. Value of this prop is used to look up according `[data-tip-target]` in DOM. If you start this value with `.` (dot), it will be evaluated as a query selector, so you can select elements that have no `[data-tip-target]` defined.


if you start with . or if it contains a space, those we use as indicators to figure out whether it's maybe a selector. we might also want to add # to that.

lsinger · 2016-12-23T16:47:47Z

client/layout/guided-tours/docs/API.md

+
+Guided Tours are declared in JSX as a tree of elements. All of them are available as named exports from `client/layout/guided-tours/config-elements`.
+
+## All-in example


instead of having the Step here, move it to ## Step below.

here you might want to add some more general advice, like, a Tour is a series of Step elements. the tour gets triggered either if selectors match or when it's forced to start through a query argument. (document the query arg somewhere, maybe where you document the tour name prop) the user can then step through the tour and get Calypso aspects explained. can be interactive in that Step element can wait for a user to do certain actions such as clicking a menu item. we can also skip tour steps depending on selectors, e.g. skip a single Step if that one doesn't work well on mobile.

lsinger · 2016-12-23T16:49:12Z

client/layout/guided-tours/docs/API.md

+* `placement`: (string, optional) Placement. Possible values: 'below', 'above', 'beside', 'center', 'middle', 'right'
+* `arrow`: (string, optional) If defined, step will get arrow pointing to a direction. Available: 'top-left', 'top-center', 'top-right',
+'right-top', 'right-middle', 'right-bottom', 'bottom-left', 'bottom-center', 'bottom-right', 'left-top', 'left-middle', 'left-bottom'
+* `style`: (object, optional) Will be used as step's inline style. Use sparingly and with caution for minor tweaks in positioning or z-indexes and avoid changing the look and feel of Guided Tours. If you use this is a way that could benefit all Guided Tours globally, please consider creating an issue.


give example so format becomes obvious

lsinger · 2016-12-23T16:50:43Z

client/layout/guided-tours/docs/API.md

+### Props
+
+* `step`: (string) Name of the step the tour will advance to.
+* `target`: (string, optional) Name of `[data-tip-target]` that would be watched.


or CSS selector

not sure actually.

I expect so, as it's calling targetForSlug internally.

I think we might want to extract docs for targetForSlug somehow and link to it from several places, where we explain target

Yeah, maybe just introduce something like a pseudo-datatype "Target" that we only use in the docs.

lsinger · 2016-12-23T16:52:38Z

client/layout/guided-tours/docs/API.md

+There are currently two ways to declare the condition to continue the tour.
+
+- Binding an `onClick` listener to a DOM node marked as `[data-tip-target]`
+- Redux selector function that evaluates to true in order to advance the tour


well, or just add a Next button

but is this really the right place to do that? this section explains how to use Continue in different ways and Next is not one of them

"There are currently two ways to declare the condition to continue the tour" is a more general statement than "here's how you use Continue", which is why I'd add the Next button (with mentioning the caveat that it's not for use with Continue, but an alternative) — or reword the "two ways" sentence.

mcsf

Looks great! Highlighted a couple of things to fix.

mcsf · 2017-01-09T16:12:32Z

client/layout/guided-tours/docs/API.md

+
+### Props
+
+* `primary` (bool, optional) If true, button will be rendered as primary. Use only if Quit is the only available action in that step.


While we're here, let's add Leif's subtle prop from #10035.

mcsf · 2017-01-09T16:12:55Z

client/layout/guided-tours/docs/API.md

+<Quit />
+
+// with a custom label
+<Quit>{ translate( 'Custom Label' ) }</Quit>`


There's a stray backtick at the end of the line

mcsf · 2017-01-09T16:14:11Z

client/layout/guided-tours/docs/API.md

+
+### Example
+
+```


Minor: make that a ```js

- Rephrased in a couple of places for clarity - Style tweaks - Fixed an NBSP character that broke Markdown highlighting.

marekhrabe added the Guided Tours label Dec 13, 2016

marekhrabe added this to the GuidedTours M6: Documentation milestone Dec 13, 2016

marekhrabe self-assigned this Dec 13, 2016

marekhrabe force-pushed the add/gt-component-docs branch from 6bb035c to 844bdb2 Compare December 14, 2016 11:05

mcsf reviewed Dec 16, 2016

View reviewed changes

hoverduck added the [Status] Needs Author Reply label Dec 21, 2016

marekhrabe added [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. and removed [Status] Needs Author Reply labels Dec 23, 2016

lsinger reviewed Dec 23, 2016

View reviewed changes

mcsf approved these changes Jan 9, 2017

View reviewed changes

marekhrabe added 9 commits January 10, 2017 10:53

add high-level descriptions

33c9898

move api to its own file, start documenting props

724e114

document shouldScrollTo

381b8ad

more docs

3bd2065

fix next label docs

8bf322f

add examples

d71ba9a

fix prop type

c6e10c4

add examples

37e513e

updated to API docs

7761ff1

marekhrabe and others added 10 commits January 10, 2017 10:53

update image

862434d

add docs for non-components

311cd26

step name usage

26adc9a

clarify step name and targeting

03612cf

Misc. changes:

eb166e8

- Rephrased in a couple of places for clarity - Style tweaks - Fixed an NBSP character that broke Markdown highlighting.

move the main example to step

308b12d

simplify tour example

4cdf5ea

add example for style usage

1f931b4

clarify options

02b2a19

addressed a for more comments from @mcsf

01eee70

lsinger force-pushed the add/gt-component-docs branch from 7a3d3e7 to 01eee70 Compare January 10, 2017 09:53

lsinger added [Status] Ready to Merge and removed [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. labels Jan 10, 2017

lsinger merged commit be177de into master Jan 10, 2017

lsinger deleted the add/gt-component-docs branch January 10, 2017 10:06

lsinger removed the [Status] Ready to Merge label Jan 10, 2017

		@@ -0,0 +1,162 @@
		# Guided Tours API

		Guided Tours are declared as a tree of JSX components.


		Note that all text content needs to be wrapped in `<p>` so it gets proper styling.

		This is just a quick and not very useful tour. You can see more examples in [TUTORIAL.md](TUTORIAL.md) or by exploring existing tours in client/layout/guided-tours/tours.


		## All-in example

		Before we go into full details, let's look at this example. It includes most possible things you can use.


		## Tour

		Tour is a React component that declares the top-level of a tour. It defines conditions for starting a tour and contains `<Step>` elements as children.


		## Step

		Step is a React component that defines a single Step of a tour. It is represented as dark box on top of Calypso UI. Step can be positioned in many ways in relation to any DOM node in Calypso that is marked with `[data-tip-target]` attribute.


		Guided Tours are declared in JSX as a tree of elements. All of them are available as named exports from `client/layout/guided-tours/config-elements`.

		## All-in example


		### Props

		* `primary` (bool, optional) If true, button will be rendered as primary. Use only if Quit is the only available action in that step.

Guided Tours: Add docs for our API #10007

Guided Tours: Add docs for our API #10007

Conversation

marekhrabe commented Dec 13, 2016 • edited by artpi

matticbot commented Dec 13, 2016

mcsf commented Dec 14, 2016

mcsf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcsf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marekhrabe commented Dec 13, 2016 •

edited by artpi