From 546bf814ca51201b7e14fbdcf30278216b45cb96 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 17:24:59 +0100
Subject: [PATCH 01/11] refine shorthand docs

---
 docs/src/views/ShorthandProps.tsx | 260 ++++++++++++++++++++++++++++--
 1 file changed, 243 insertions(+), 17 deletions(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index af300df509..fdc60d3bd3 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -1,37 +1,263 @@
 import * as React from 'react'
 import { NavLink } from 'react-router-dom'
+import { Header } from 'semantic-ui-react'
 import DocPage from '../components/DocPage/DocPage'
 import CodeSnippet from '../components/CodeSnippet'
 import Button from '../../../src/components/Button/Button'
 
+const joinToString = stringOrArray => {
+  if (typeof stringOrArray === 'string') {
+    return stringOrArray
+  }
+
+  return stringOrArray.join('\n')
+}
+
+const header = content => <Header as="h2">{content}</Header>
+const subheader = content => <Header as="h3">{content}</Header>
+
+const code = content => <code>{content}</code>
+const codeExample = snippet => <CodeSnippet value={joinToString(snippet)} />
+
 class ShorthandProps extends React.Component {
   render() {
     return (
       <DocPage title="Shorthand Props">
         <p>
-          Most components support two APIs: <code>shorthand</code> and <code>children</code>. With
-          the <code>shorthand</code> definition we are adding some props to the component in order
-          to define it’s content and behavior.
+          It is quite common for Stardust component to have "slots" which accept shorthand values.
+          For example, {code('Button')} component has an {code('icon')} slot which value defines the
+          icon that will be rendered.
+        </p>
+
+        {codeExample([`<Button icon='chess rook' />`])}
+
+        <p>
+          So, what this string value (i.e. {code("'chess rook'")}) means for {code('Button')}{' '}
+          component and, essentially, how it transforms into rendered {code('<Icon />')} element?
+        </p>
+
+        <p>
+          There are several forms of shorthand values that can be provided, but all of them share
+          one common thing - each is eventually evaluated to React Element. Thus, you can think of
+          shorthand values as a recipe to customize rendered React Element at corresponding slot.
+        </p>
+
+        {/* SHORTHAND AS AN OBJECT */}
+        {header('Shorthand value as Object')}
+        <p>
+          Each component's slot has associated default element type. For example, by default there
+          is {code('<Icon />')} element rendered for {code('Button')}'s {code('icon')} slot. It is
+          possible to customize props of this default element by providing props object as shorthand
+          value:
+        </p>
+
+        {codeExample([
+          `// 'name' and 'size' will be used as <Icon /> element's props`,
+          `<Button icon={{ name: 'chess rook', size: 'small' }} />`,
+        ])}
+
+        {/* SHORTHAND AS A PRIMITIVE VALUE */}
+        {header('Shorthand value as Primitive')}
+        <p>
+          There is even shorter way to define default element's props - by using a primitive value.
+          In that case provided shorthand value will be taken as a value for 'default prop' of this
+          default element.
+        </p>
+
+        <p>
+          This could be much easier seen with an example. Here, again, we have a {code('Button')}{' '}
+          element with its icon being defined with shorthand - where provided {code('string')} value
+          will be used as icon's {code('name')}:
+        </p>
+
+        {codeExample([
+          `<>`,
+          `  <Button icon='chess rook' />`,
+          ``,
+          `  {/* has identical effect to the previous one */}`,
+          `  <Button icon={{ name: 'chess rook' }} />`,
+          `</>`,
+        ])}
+        <p>
+          This works because {code('name')} is the default prop of slot's {code('<Icon />')}{' '}
+          element.
+        </p>
+
+        {/* SHORTHAND AS REACT ELEMENT */}
+        {header('Shorthand value as React Element')}
+        <p>
+          There are cases where it might be necessary to customize element tree that will be
+          rendered as a slot's value. Returning to {code('Button')} example, we might want to render{' '}
+          {code('<i />')} instead of default {code('<Icon />')} element. In that case necessary
+          element might be directly provided as shorthand value:
+        </p>
+        {codeExample([`<Button icon={<i class='my-icon'></i>} />`])}
+
+        <blockquote>
+          <strong>
+            There is a very important caveat here, though: whenever React Element is directly used
+            as a shorthand value, it becomes client's responsibility to handle some aspects that
+            Stardust was originally responsible for (such as {code('styles')} or{' '}
+            {code('accessibility')}).
+          </strong>{' '}
+          This is because, in contrast to other forms of shorthand values, Stardust-evaluated props
+          cannot be unsafely passed to the element which type is, generally, doesn't allow Stardust
+          to make any prior assumptions about. Due to this limitation, you should strive to use
+          other options for shorthand values whenever is possible - for instance, this is how
+          previous example can be rewritten:
+        </blockquote>
+        {codeExample([`<Button icon={{ as: 'i', className: 'my-icon' }} />`])}
+
+        <p>
+          However, there still might be cases where it would be impossible to use object form of the
+          shorthand value - for example, you might want to render some custom elements tree for the
+          slot, while wanting to preserve calculated styles and accessibility aspects for it. In
+          that case {code('render')} callback of function shorthand value should be used.
+        </p>
+
+        {/* SHORTHAND AS A FUNCTION */}
+        {header('Shorthand value as Function')}
+        <p>
+          Providing function as a shorthand value is the most involving but, at the same time, the
+          most powerful option for customizing component's slot. The only requirements for this
+          function are:
+        </p>
+
+        <ul>
+          <li>it should finish syncronously</li>
+          <li>it should return React Element as a result</li>
+        </ul>
+
+        <p>Thus, in its simplest form, it could be used the following way:</p>
+
+        {codeExample([`<Button icon={() => <Icon name='chess rook' />} />`])}
+
+        <p>
+          However, if it will be just about that, this function form wouldn't introduce any
+          additional value. So, lets take a look on the scenarios where it is really helpful.
+        </p>
+
+        {subheader(`'Render' callback argument`)}
+        <p>
+          When function is provided as a shorthand value, there is a {code('render')} callback
+          provided as its argument. This {code('render')} argument is a function that 'knows' how to
+          render all the previously considered shorthand types - i.e. primitive values, objects,
+          React Elements.
         </p>
+
+        <p>Here is an example that represents this:</p>
+
+        {codeExample([
+          `<>`,
+          `  {/* All three have the same effect: */}`,
+          `  <Button icon='chess rook' />`,
+          ``,
+          `  {/* render() transforms string to <Icon /> element */}`,
+          `  <Button icon={render => render('chess rook')} />`,
+          ``,
+          `  {/* render() transforms object to <Icon /> element */}`,
+          `  <Button icon={render => render({ name: 'chess rook' })} />`,
+          `</>`,
+        ])}
+
+        {subheader(`Handle Async data loading scenarios`)}
         <p>
-          When defining the icon and text content displayed in the Button component, we can pass the
-          <code>icon</code> and <code>content</code> props.
+          This 'render callback' arg makes it possible for the client to tackle scenarios where
+          slot's data may be fetched asynchronously.
         </p>
-        <CodeSnippet value={'<Button icon="user" content="Click me!" />'} />
 
         <p>
-          With the <code>children</code> API, you are responsible for constructing the proper
-          markup. You are also responsible for managing the component's state, styling, and
-          accessibility. Due to this, you should strive to use the shorthand API wherever possible.
-          It is best to leave the details to the component to solve for you.
+          Consider the following scenario: suppose we need to render {code('Button')}'s icon, but
+          the problem is that icon's name is fetched from some remote source. Thus, we cannot do it
+          as simply as that, as icon's name is not known at the moment {code('Button')} is rendered:
         </p>
-        <CodeSnippet
-          value={[
-            `<Button icon iconOnly primary>`,
-            `  <Icon name="book" xSpacing="none" />`,
-            `</Button>`,
-          ].join('\n')}
-        />
+
+        {codeExample([`<Button icon={{ name: /* unknown yet */ undefined }} />`])}
+
+        <p>
+          It is quite common case that there is some component that is responsible for data fetching
+          abstraction - and it is possible to 'tell' this component what should be rendered while
+          data is loading, as well as what should be rendered when data is fetched.
+        </p>
+        {codeExample([
+          `<AsyncData`,
+          `  getData={fetch('https://some/url')}`,
+          `  onLoading={<div>Loading..</div>} // renders when data is loading`,
+          `  onLoaded={data => <div>Loaded Data: {data}</div>} // renders once data is fetched`,
+          `/>`,
+        ])}
+
+        <p>
+          Lets suppose that we want to render 'loading' icon before data is fetched, and switch it
+          with the icon which {code('name')} will be provided by fetched {code('data')} object.
+          Also, note that we have {code('render')} arg that knows <em>how</em> to render{' '}
+          {code('Button')}'s icons.
+        </p>
+
+        <p>Putting it all together, we will address our async data fetch case:</p>
+        {codeExample([
+          `<Button`,
+          `  icon={render => <AsyncData`,
+          `    getData={fetch('https://some/url')}`,
+          `    onLoading={<Icon name='loading' />}`,
+          `    /* using 'render' arg here to render icon from loaded name */`,
+          `    onLoaded={data => render({ name: data.iconName })}`,
+          `  />}`,
+          `/>`,
+        ])}
+
+        <p>
+          Note that this example can be further simplified, as {code('render')} can be used to
+          render 'loading' icon as well:
+        </p>
+        {codeExample([
+          `<Button`,
+          `  icon={render => <AsyncData`,
+          `    getData={fetch('https://some/url')}`,
+          `    /* using 'render' arg here to render loading icon as well */`,
+          `    onLoading={render('loading')}`,
+          `    onLoaded={data => render({ name: data.iconName })}`,
+          `  />}`,
+          `/>`,
+        ])}
+
+        {subheader(`Customizing rendered tree`)}
+        <p>
+          There is another use case that {code('render')} callback arg is very useful for - this is
+          the case where custom element's tree should be rendered for the slot, but, at the same
+          time, all the evaluated styles and accessibility behaviors should be preserved for
+          rendered custom element.
+        </p>
+
+        <p>
+          As you might recall, there is a problem that might happen when React Element is provided
+          directly as shorthand value - in that case Stardust props are not propagated to rendered
+          element, which may result in broken styles and accessibility. In order to avoid that the
+          following strategy should be considered:
+        </p>
+
+        {codeExample([
+          `<Button icon={render => render(`,
+          `  /* what to render */`,
+          `  { name: 'chess rook' },`,
+          ``,
+          `  /* how to render */`,
+          `  (ComponentType, props) => (`,
+          `    <div class='my-icon-container'>`,
+          `      <i {...props} />`,
+          `    </div>`,
+          `  )`,
+          `)} />`,
+        ])}
+
+        <p>
+          Here we are passing a recipe of how evaluated {code('ComponentType')} ({code('Icon')} in
+          our case, which is ignored by the rendered tree) and {code('props')} should be passed to
+          custom elements tree. Note that {code('props')} object, amongst others, contains all the
+          necessary evaluated styles and accessibility aspects that should be applied to rendered
+          element, so that nothing will be lost.
+        </p>
+
         <br />
         <Button as={NavLink} content="Quick Start" icon="arrow right" primary to="quick-start" />
       </DocPage>

From 50a3427d749095b091ac14ae741855732ce35adc Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 17:29:14 +0100
Subject: [PATCH 02/11] update changelog

---
 CHANGELOG.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e3c5c0420..a97d3aad4d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,9 +17,6 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-### Features
-- Expose `renderItem` and `renderSelectedItem` callbacks API for `Dropdown` @layershifter ([#746](https://github.com/stardust-ui/react/pull/746))
-
 ### Fixes
 - Fix focus outline visible only during keyboard navigation in `ListItem` @layershifter ([#727](https://github.com/stardust-ui/react/pull/727))
 - Pass `jest --detectLeaks` tests @miroslavstastny ([#718](https://github.com/stardust-ui/react/pull/718))
@@ -29,6 +26,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Features
 - Rename `Slot` component to `Box` and export it @Bugaa92 ([#713](https://github.com/stardust-ui/react/pull/713))
 - Add `Indicator` component and used it in `MenuItem` and `AccordionTitle` @mnajdova ([#721](https://github.com/stardust-ui/react/pull/721))
+- Expose `renderItem` and `renderSelectedItem` callbacks API for `Dropdown` @layershifter ([#746](https://github.com/stardust-ui/react/pull/746))
+- Refine Shorthand docs page content @kuzhelov ([#751](https://github.com/stardust-ui/react/pull/751))
 
 <!--------------------------------[ v0.17.0 ]------------------------------- -->
 ## [v0.17.0](https://github.com/stardust-ui/react/tree/v0.17.0) (2019-01-17)

From 41fb68c7e1d308c6463891889632dbd2da4660c5 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:07:11 +0100
Subject: [PATCH 03/11] fix section of changelog entry

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a97d3aad4d..a62e195677 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Rename `Slot` component to `Box` and export it @Bugaa92 ([#713](https://github.com/stardust-ui/react/pull/713))
 - Add `Indicator` component and used it in `MenuItem` and `AccordionTitle` @mnajdova ([#721](https://github.com/stardust-ui/react/pull/721))
 - Expose `renderItem` and `renderSelectedItem` callbacks API for `Dropdown` @layershifter ([#746](https://github.com/stardust-ui/react/pull/746))
+
+### Documentation
 - Refine Shorthand docs page content @kuzhelov ([#751](https://github.com/stardust-ui/react/pull/751))
 
 <!--------------------------------[ v0.17.0 ]------------------------------- -->

From 30f8253847e584937302c7fe8fa8b2141a7bcf41 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:08:00 +0100
Subject: [PATCH 04/11] remove unnecessary paragraph

---
 docs/src/views/ShorthandProps.tsx | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index fdc60d3bd3..f12642650f 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -31,11 +31,6 @@ class ShorthandProps extends React.Component {
 
         {codeExample([`<Button icon='chess rook' />`])}
 
-        <p>
-          So, what this string value (i.e. {code("'chess rook'")}) means for {code('Button')}{' '}
-          component and, essentially, how it transforms into rendered {code('<Icon />')} element?
-        </p>
-
         <p>
           There are several forms of shorthand values that can be provided, but all of them share
           one common thing - each is eventually evaluated to React Element. Thus, you can think of

From 5fa95d840184424766759aeb6b76def1b8742c89 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:09:05 +0100
Subject: [PATCH 05/11] eliminate default-default repetition

---
 docs/src/views/ShorthandProps.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index f12642650f..62d509527c 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -56,7 +56,7 @@ class ShorthandProps extends React.Component {
         <p>
           There is even shorter way to define default element's props - by using a primitive value.
           In that case provided shorthand value will be taken as a value for 'default prop' of this
-          default element.
+          element.
         </p>
 
         <p>

From 306572e0622553043e613337d81bd3b0ee861913 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:09:46 +0100
Subject: [PATCH 06/11] 'unsafely' -> 'safely'

---
 docs/src/views/ShorthandProps.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index 62d509527c..f5a10ef58a 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -96,10 +96,10 @@ class ShorthandProps extends React.Component {
             {code('accessibility')}).
           </strong>{' '}
           This is because, in contrast to other forms of shorthand values, Stardust-evaluated props
-          cannot be unsafely passed to the element which type is, generally, doesn't allow Stardust
-          to make any prior assumptions about. Due to this limitation, you should strive to use
-          other options for shorthand values whenever is possible - for instance, this is how
-          previous example can be rewritten:
+          cannot be safely passed to the element which type is, generally, doesn't allow Stardust to
+          make any prior assumptions about. Due to this limitation, you should strive to use other
+          options for shorthand values whenever is possible - for instance, this is how previous
+          example can be rewritten:
         </blockquote>
         {codeExample([`<Button icon={{ as: 'i', className: 'my-icon' }} />`])}
 

From af3247d5975c3bb57841ab414354a0adad21a349 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:18:39 +0100
Subject: [PATCH 07/11] improve custom tree rendering example

---
 docs/src/views/ShorthandProps.tsx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index f5a10ef58a..441cce5376 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -239,7 +239,7 @@ class ShorthandProps extends React.Component {
           `  /* how to render */`,
           `  (ComponentType, props) => (`,
           `    <div class='my-icon-container'>`,
-          `      <i {...props} />`,
+          `      <i class="my-chess-rook-icon" {...props.accessibility.root} />`,
           `    </div>`,
           `  )`,
           `)} />`,
@@ -249,8 +249,7 @@ class ShorthandProps extends React.Component {
           Here we are passing a recipe of how evaluated {code('ComponentType')} ({code('Icon')} in
           our case, which is ignored by the rendered tree) and {code('props')} should be passed to
           custom elements tree. Note that {code('props')} object, amongst others, contains all the
-          necessary evaluated styles and accessibility aspects that should be applied to rendered
-          element, so that nothing will be lost.
+          necessary evaluated accessibility attributes that should be applied to rendered element.
         </p>
 
         <br />

From 955da826302c503a43ea5445e1f6e20811136216 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Mon, 21 Jan 2019 18:45:23 +0100
Subject: [PATCH 08/11] add note about falsy shorthand values

---
 docs/src/views/ShorthandProps.tsx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index 441cce5376..9aa934dc20 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -78,6 +78,13 @@ class ShorthandProps extends React.Component {
           element.
         </p>
 
+        {subheader(`Disable slot's rendering`)}
+        <p>
+          It is also possible to pass falsy values ({code('false')}, {code('null')} or{' '}
+          {code('undefined')}) to shorthand prop - in that case there will be nothing rendered for
+          the component's slot.
+        </p>
+
         {/* SHORTHAND AS REACT ELEMENT */}
         {header('Shorthand value as React Element')}
         <p>

From 0d72500ebb7c7b7f831880254f499bc4617340c7 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Tue, 22 Jan 2019 11:40:30 +0100
Subject: [PATCH 09/11] make page component being functional

---
 docs/src/views/ShorthandProps.tsx | 482 +++++++++++++++---------------
 1 file changed, 236 insertions(+), 246 deletions(-)

diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index 9aa934dc20..00f1d98029 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -19,251 +19,241 @@ const subheader = content => <Header as="h3">{content}</Header>
 const code = content => <code>{content}</code>
 const codeExample = snippet => <CodeSnippet value={joinToString(snippet)} />
 
-class ShorthandProps extends React.Component {
-  render() {
-    return (
-      <DocPage title="Shorthand Props">
-        <p>
-          It is quite common for Stardust component to have "slots" which accept shorthand values.
-          For example, {code('Button')} component has an {code('icon')} slot which value defines the
-          icon that will be rendered.
-        </p>
-
-        {codeExample([`<Button icon='chess rook' />`])}
-
-        <p>
-          There are several forms of shorthand values that can be provided, but all of them share
-          one common thing - each is eventually evaluated to React Element. Thus, you can think of
-          shorthand values as a recipe to customize rendered React Element at corresponding slot.
-        </p>
-
-        {/* SHORTHAND AS AN OBJECT */}
-        {header('Shorthand value as Object')}
-        <p>
-          Each component's slot has associated default element type. For example, by default there
-          is {code('<Icon />')} element rendered for {code('Button')}'s {code('icon')} slot. It is
-          possible to customize props of this default element by providing props object as shorthand
-          value:
-        </p>
-
-        {codeExample([
-          `// 'name' and 'size' will be used as <Icon /> element's props`,
-          `<Button icon={{ name: 'chess rook', size: 'small' }} />`,
-        ])}
-
-        {/* SHORTHAND AS A PRIMITIVE VALUE */}
-        {header('Shorthand value as Primitive')}
-        <p>
-          There is even shorter way to define default element's props - by using a primitive value.
-          In that case provided shorthand value will be taken as a value for 'default prop' of this
-          element.
-        </p>
-
-        <p>
-          This could be much easier seen with an example. Here, again, we have a {code('Button')}{' '}
-          element with its icon being defined with shorthand - where provided {code('string')} value
-          will be used as icon's {code('name')}:
-        </p>
-
-        {codeExample([
-          `<>`,
-          `  <Button icon='chess rook' />`,
-          ``,
-          `  {/* has identical effect to the previous one */}`,
-          `  <Button icon={{ name: 'chess rook' }} />`,
-          `</>`,
-        ])}
-        <p>
-          This works because {code('name')} is the default prop of slot's {code('<Icon />')}{' '}
-          element.
-        </p>
-
-        {subheader(`Disable slot's rendering`)}
-        <p>
-          It is also possible to pass falsy values ({code('false')}, {code('null')} or{' '}
-          {code('undefined')}) to shorthand prop - in that case there will be nothing rendered for
-          the component's slot.
-        </p>
-
-        {/* SHORTHAND AS REACT ELEMENT */}
-        {header('Shorthand value as React Element')}
-        <p>
-          There are cases where it might be necessary to customize element tree that will be
-          rendered as a slot's value. Returning to {code('Button')} example, we might want to render{' '}
-          {code('<i />')} instead of default {code('<Icon />')} element. In that case necessary
-          element might be directly provided as shorthand value:
-        </p>
-        {codeExample([`<Button icon={<i class='my-icon'></i>} />`])}
-
-        <blockquote>
-          <strong>
-            There is a very important caveat here, though: whenever React Element is directly used
-            as a shorthand value, it becomes client's responsibility to handle some aspects that
-            Stardust was originally responsible for (such as {code('styles')} or{' '}
-            {code('accessibility')}).
-          </strong>{' '}
-          This is because, in contrast to other forms of shorthand values, Stardust-evaluated props
-          cannot be safely passed to the element which type is, generally, doesn't allow Stardust to
-          make any prior assumptions about. Due to this limitation, you should strive to use other
-          options for shorthand values whenever is possible - for instance, this is how previous
-          example can be rewritten:
-        </blockquote>
-        {codeExample([`<Button icon={{ as: 'i', className: 'my-icon' }} />`])}
-
-        <p>
-          However, there still might be cases where it would be impossible to use object form of the
-          shorthand value - for example, you might want to render some custom elements tree for the
-          slot, while wanting to preserve calculated styles and accessibility aspects for it. In
-          that case {code('render')} callback of function shorthand value should be used.
-        </p>
-
-        {/* SHORTHAND AS A FUNCTION */}
-        {header('Shorthand value as Function')}
-        <p>
-          Providing function as a shorthand value is the most involving but, at the same time, the
-          most powerful option for customizing component's slot. The only requirements for this
-          function are:
-        </p>
-
-        <ul>
-          <li>it should finish syncronously</li>
-          <li>it should return React Element as a result</li>
-        </ul>
-
-        <p>Thus, in its simplest form, it could be used the following way:</p>
-
-        {codeExample([`<Button icon={() => <Icon name='chess rook' />} />`])}
-
-        <p>
-          However, if it will be just about that, this function form wouldn't introduce any
-          additional value. So, lets take a look on the scenarios where it is really helpful.
-        </p>
-
-        {subheader(`'Render' callback argument`)}
-        <p>
-          When function is provided as a shorthand value, there is a {code('render')} callback
-          provided as its argument. This {code('render')} argument is a function that 'knows' how to
-          render all the previously considered shorthand types - i.e. primitive values, objects,
-          React Elements.
-        </p>
-
-        <p>Here is an example that represents this:</p>
-
-        {codeExample([
-          `<>`,
-          `  {/* All three have the same effect: */}`,
-          `  <Button icon='chess rook' />`,
-          ``,
-          `  {/* render() transforms string to <Icon /> element */}`,
-          `  <Button icon={render => render('chess rook')} />`,
-          ``,
-          `  {/* render() transforms object to <Icon /> element */}`,
-          `  <Button icon={render => render({ name: 'chess rook' })} />`,
-          `</>`,
-        ])}
-
-        {subheader(`Handle Async data loading scenarios`)}
-        <p>
-          This 'render callback' arg makes it possible for the client to tackle scenarios where
-          slot's data may be fetched asynchronously.
-        </p>
-
-        <p>
-          Consider the following scenario: suppose we need to render {code('Button')}'s icon, but
-          the problem is that icon's name is fetched from some remote source. Thus, we cannot do it
-          as simply as that, as icon's name is not known at the moment {code('Button')} is rendered:
-        </p>
-
-        {codeExample([`<Button icon={{ name: /* unknown yet */ undefined }} />`])}
-
-        <p>
-          It is quite common case that there is some component that is responsible for data fetching
-          abstraction - and it is possible to 'tell' this component what should be rendered while
-          data is loading, as well as what should be rendered when data is fetched.
-        </p>
-        {codeExample([
-          `<AsyncData`,
-          `  getData={fetch('https://some/url')}`,
-          `  onLoading={<div>Loading..</div>} // renders when data is loading`,
-          `  onLoaded={data => <div>Loaded Data: {data}</div>} // renders once data is fetched`,
-          `/>`,
-        ])}
-
-        <p>
-          Lets suppose that we want to render 'loading' icon before data is fetched, and switch it
-          with the icon which {code('name')} will be provided by fetched {code('data')} object.
-          Also, note that we have {code('render')} arg that knows <em>how</em> to render{' '}
-          {code('Button')}'s icons.
-        </p>
-
-        <p>Putting it all together, we will address our async data fetch case:</p>
-        {codeExample([
-          `<Button`,
-          `  icon={render => <AsyncData`,
-          `    getData={fetch('https://some/url')}`,
-          `    onLoading={<Icon name='loading' />}`,
-          `    /* using 'render' arg here to render icon from loaded name */`,
-          `    onLoaded={data => render({ name: data.iconName })}`,
-          `  />}`,
-          `/>`,
-        ])}
-
-        <p>
-          Note that this example can be further simplified, as {code('render')} can be used to
-          render 'loading' icon as well:
-        </p>
-        {codeExample([
-          `<Button`,
-          `  icon={render => <AsyncData`,
-          `    getData={fetch('https://some/url')}`,
-          `    /* using 'render' arg here to render loading icon as well */`,
-          `    onLoading={render('loading')}`,
-          `    onLoaded={data => render({ name: data.iconName })}`,
-          `  />}`,
-          `/>`,
-        ])}
-
-        {subheader(`Customizing rendered tree`)}
-        <p>
-          There is another use case that {code('render')} callback arg is very useful for - this is
-          the case where custom element's tree should be rendered for the slot, but, at the same
-          time, all the evaluated styles and accessibility behaviors should be preserved for
-          rendered custom element.
-        </p>
-
-        <p>
-          As you might recall, there is a problem that might happen when React Element is provided
-          directly as shorthand value - in that case Stardust props are not propagated to rendered
-          element, which may result in broken styles and accessibility. In order to avoid that the
-          following strategy should be considered:
-        </p>
-
-        {codeExample([
-          `<Button icon={render => render(`,
-          `  /* what to render */`,
-          `  { name: 'chess rook' },`,
-          ``,
-          `  /* how to render */`,
-          `  (ComponentType, props) => (`,
-          `    <div class='my-icon-container'>`,
-          `      <i class="my-chess-rook-icon" {...props.accessibility.root} />`,
-          `    </div>`,
-          `  )`,
-          `)} />`,
-        ])}
-
-        <p>
-          Here we are passing a recipe of how evaluated {code('ComponentType')} ({code('Icon')} in
-          our case, which is ignored by the rendered tree) and {code('props')} should be passed to
-          custom elements tree. Note that {code('props')} object, amongst others, contains all the
-          necessary evaluated accessibility attributes that should be applied to rendered element.
-        </p>
-
-        <br />
-        <Button as={NavLink} content="Quick Start" icon="arrow right" primary to="quick-start" />
-      </DocPage>
-    )
-  }
-}
+const ShorthandProps = props => (
+  <DocPage title="Shorthand Props">
+    <p>
+      It is quite common for Stardust component to have "slots" which accept shorthand values. For
+      example, {code('Button')} component has an {code('icon')} slot which value defines the icon
+      that will be rendered.
+    </p>
+
+    {codeExample([`<Button icon='chess rook' />`])}
+
+    <p>
+      There are several forms of shorthand values that can be provided, but all of them share one
+      common thing - each is eventually evaluated to React Element. Thus, you can think of shorthand
+      values as a recipe to customize rendered React Element at corresponding slot.
+    </p>
+
+    {/* SHORTHAND AS AN OBJECT */}
+    {header('Shorthand value as Object')}
+    <p>
+      Each component's slot has associated default element type. For example, by default there is{' '}
+      {code('<Icon />')} element rendered for {code('Button')}'s {code('icon')} slot. It is possible
+      to customize props of this default element by providing props object as shorthand value:
+    </p>
+
+    {codeExample([
+      `// 'name' and 'size' will be used as <Icon /> element's props`,
+      `<Button icon={{ name: 'chess rook', size: 'small' }} />`,
+    ])}
+
+    {/* SHORTHAND AS A PRIMITIVE VALUE */}
+    {header('Shorthand value as Primitive')}
+    <p>
+      There is even shorter way to define default element's props - by using a primitive value. In
+      that case provided shorthand value will be taken as a value for 'default prop' of this
+      element.
+    </p>
+
+    <p>
+      This could be much easier seen with an example. Here, again, we have a {code('Button')}{' '}
+      element with its icon being defined with shorthand - where provided {code('string')} value
+      will be used as icon's {code('name')}:
+    </p>
+
+    {codeExample([
+      `<>`,
+      `  <Button icon='chess rook' />`,
+      ``,
+      `  {/* has identical effect to the previous one */}`,
+      `  <Button icon={{ name: 'chess rook' }} />`,
+      `</>`,
+    ])}
+    <p>
+      This works because {code('name')} is the default prop of slot's {code('<Icon />')} element.
+    </p>
+
+    {subheader(`Disable slot's rendering`)}
+    <p>
+      It is also possible to pass falsy values ({code('false')}, {code('null')} or{' '}
+      {code('undefined')}) to shorthand prop - in that case there will be nothing rendered for the
+      component's slot.
+    </p>
+
+    {/* SHORTHAND AS REACT ELEMENT */}
+    {header('Shorthand value as React Element')}
+    <p>
+      There are cases where it might be necessary to customize element tree that will be rendered as
+      a slot's value. Returning to {code('Button')} example, we might want to render {code('<i />')}{' '}
+      instead of default {code('<Icon />')} element. In that case necessary element might be
+      directly provided as shorthand value:
+    </p>
+    {codeExample([`<Button icon={<i class='my-icon'></i>} />`])}
+
+    <blockquote>
+      <strong>
+        There is a very important caveat here, though: whenever React Element is directly used as a
+        shorthand value, it becomes client's responsibility to handle some aspects that Stardust was
+        originally responsible for (such as {code('styles')} or {code('accessibility')}).
+      </strong>{' '}
+      This is because, in contrast to other forms of shorthand values, Stardust-evaluated props
+      cannot be safely passed to the element which type is, generally, doesn't allow Stardust to
+      make any prior assumptions about. Due to this limitation, you should strive to use other
+      options for shorthand values whenever is possible - for instance, this is how previous example
+      can be rewritten:
+    </blockquote>
+    {codeExample([`<Button icon={{ as: 'i', className: 'my-icon' }} />`])}
+
+    <p>
+      However, there still might be cases where it would be impossible to use object form of the
+      shorthand value - for example, you might want to render some custom elements tree for the
+      slot, while wanting to preserve calculated styles and accessibility aspects for it. In that
+      case {code('render')} callback of function shorthand value should be used.
+    </p>
+
+    {/* SHORTHAND AS A FUNCTION */}
+    {header('Shorthand value as Function')}
+    <p>
+      Providing function as a shorthand value is the most involving but, at the same time, the most
+      powerful option for customizing component's slot. The only requirements for this function are:
+    </p>
+
+    <ul>
+      <li>it should finish syncronously</li>
+      <li>it should return React Element as a result</li>
+    </ul>
+
+    <p>Thus, in its simplest form, it could be used the following way:</p>
+
+    {codeExample([`<Button icon={() => <Icon name='chess rook' />} />`])}
+
+    <p>
+      However, if it will be just about that, this function form wouldn't introduce any additional
+      value. So, lets take a look on the scenarios where it is really helpful.
+    </p>
+
+    {subheader(`'Render' callback argument`)}
+    <p>
+      When function is provided as a shorthand value, there is a {code('render')} callback provided
+      as its argument. This {code('render')} argument is a function that 'knows' how to render all
+      the previously considered shorthand types - i.e. primitive values, objects, React Elements.
+    </p>
+
+    <p>Here is an example that represents this:</p>
+
+    {codeExample([
+      `<>`,
+      `  {/* All three have the same effect: */}`,
+      `  <Button icon='chess rook' />`,
+      ``,
+      `  {/* render() transforms string to <Icon /> element */}`,
+      `  <Button icon={render => render('chess rook')} />`,
+      ``,
+      `  {/* render() transforms object to <Icon /> element */}`,
+      `  <Button icon={render => render({ name: 'chess rook' })} />`,
+      `</>`,
+    ])}
+
+    {subheader(`Handle Async data loading scenarios`)}
+    <p>
+      This 'render callback' arg makes it possible for the client to tackle scenarios where slot's
+      data may be fetched asynchronously.
+    </p>
+
+    <p>
+      Consider the following scenario: suppose we need to render {code('Button')}'s icon, but the
+      problem is that icon's name is fetched from some remote source. Thus, we cannot do it as
+      simply as that, as icon's name is not known at the moment {code('Button')} is rendered:
+    </p>
+
+    {codeExample([`<Button icon={{ name: /* unknown yet */ undefined }} />`])}
+
+    <p>
+      It is quite common case that there is some component that is responsible for data fetching
+      abstraction - and it is possible to 'tell' this component what should be rendered while data
+      is loading, as well as what should be rendered when data is fetched.
+    </p>
+    {codeExample([
+      `<AsyncData`,
+      `  getData={fetch('https://some/url')}`,
+      `  onLoading={<div>Loading..</div>} // renders when data is loading`,
+      `  onLoaded={data => <div>Loaded Data: {data}</div>} // renders once data is fetched`,
+      `/>`,
+    ])}
+
+    <p>
+      Lets suppose that we want to render 'loading' icon before data is fetched, and switch it with
+      the icon which {code('name')} will be provided by fetched {code('data')} object. Also, note
+      that we have {code('render')} arg that knows <em>how</em> to render {code('Button')}'s icons.
+    </p>
+
+    <p>Putting it all together, we will address our async data fetch case:</p>
+    {codeExample([
+      `<Button`,
+      `  icon={render => <AsyncData`,
+      `    getData={fetch('https://some/url')}`,
+      `    onLoading={<Icon name='loading' />}`,
+      `    /* using 'render' arg here to render icon from loaded name */`,
+      `    onLoaded={data => render({ name: data.iconName })}`,
+      `  />}`,
+      `/>`,
+    ])}
+
+    <p>
+      Note that this example can be further simplified, as {code('render')} can be used to render
+      'loading' icon as well:
+    </p>
+    {codeExample([
+      `<Button`,
+      `  icon={render => <AsyncData`,
+      `    getData={fetch('https://some/url')}`,
+      `    /* using 'render' arg here to render loading icon as well */`,
+      `    onLoading={render('loading')}`,
+      `    onLoaded={data => render({ name: data.iconName })}`,
+      `  />}`,
+      `/>`,
+    ])}
+
+    {subheader(`Customizing rendered tree`)}
+    <p>
+      There is another use case that {code('render')} callback arg is very useful for - this is the
+      case where custom element's tree should be rendered for the slot, but, at the same time, all
+      the evaluated styles and accessibility behaviors should be preserved for rendered custom
+      element.
+    </p>
+
+    <p>
+      As you might recall, there is a problem that might happen when React Element is provided
+      directly as shorthand value - in that case Stardust props are not propagated to rendered
+      element, which may result in broken styles and accessibility. In order to avoid that the
+      following strategy should be considered:
+    </p>
+
+    {codeExample([
+      `<Button icon={render => render(`,
+      `  /* what to render */`,
+      `  { name: 'chess rook' },`,
+      ``,
+      `  /* how to render */`,
+      `  (ComponentType, props) => (`,
+      `    <div class='my-icon-container'>`,
+      `      <i class="my-chess-rook-icon" {...props.accessibility.root} />`,
+      `    </div>`,
+      `  )`,
+      `)} />`,
+    ])}
+
+    <p>
+      Here we are passing a recipe of how evaluated {code('ComponentType')} ({code('Icon')} in our
+      case, which is ignored by the rendered tree) and {code('props')} should be passed to custom
+      elements tree. Note that {code('props')} object, amongst others, contains all the necessary
+      evaluated accessibility attributes that should be applied to rendered element.
+    </p>
+
+    <br />
+    <Button as={NavLink} content="Quick Start" icon="arrow right" primary to="quick-start" />
+  </DocPage>
+)
 
 export default ShorthandProps

From 2254aa02aba21e2e5bffdac5e54a1c3691815631 Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Tue, 22 Jan 2019 11:44:11 +0100
Subject: [PATCH 10/11] accept string arrays as value of code snippet

---
 docs/src/components/CodeSnippet.tsx | 12 ++++++++++--
 docs/src/views/ShorthandProps.tsx   | 14 +++-----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/src/components/CodeSnippet.tsx b/docs/src/components/CodeSnippet.tsx
index 8231eed77d..81e3e122e0 100644
--- a/docs/src/components/CodeSnippet.tsx
+++ b/docs/src/components/CodeSnippet.tsx
@@ -7,10 +7,18 @@ export interface CodeSnippetProps {
   fitted?: boolean
   label?: string
   mode?: 'jsx' | 'html' | 'sh'
-  value: string
+  value: string | string[]
   style?: React.CSSProperties
 }
 
+const joinToString = stringOrArray => {
+  if (typeof stringOrArray === 'string') {
+    return stringOrArray
+  }
+
+  return stringOrArray.join('\n')
+}
+
 const formatters = {
   sh: (val: string = ''): string => val.replace(/^/g, '$  '),
   html: (val: string = ''): string => formatCode(val, 'html'),
@@ -19,7 +27,7 @@ const formatters = {
 
 const CodeSnippet = ({ fitted, label, value, mode = 'jsx', ...restProps }: CodeSnippetProps) => {
   const format = formatters[mode]
-  const formattedValue = format(value)
+  const formattedValue = format(joinToString(value))
     // remove eof line break, they are not helpful for snippets
     .replace(/\n$/, '')
 
diff --git a/docs/src/views/ShorthandProps.tsx b/docs/src/views/ShorthandProps.tsx
index 00f1d98029..469bb5a2dd 100644
--- a/docs/src/views/ShorthandProps.tsx
+++ b/docs/src/views/ShorthandProps.tsx
@@ -5,19 +5,11 @@ import DocPage from '../components/DocPage/DocPage'
 import CodeSnippet from '../components/CodeSnippet'
 import Button from '../../../src/components/Button/Button'
 
-const joinToString = stringOrArray => {
-  if (typeof stringOrArray === 'string') {
-    return stringOrArray
-  }
-
-  return stringOrArray.join('\n')
-}
-
 const header = content => <Header as="h2">{content}</Header>
 const subheader = content => <Header as="h3">{content}</Header>
 
 const code = content => <code>{content}</code>
-const codeExample = snippet => <CodeSnippet value={joinToString(snippet)} />
+const codeExample = snippet => <CodeSnippet value={snippet} />
 
 const ShorthandProps = props => (
   <DocPage title="Shorthand Props">
@@ -27,7 +19,7 @@ const ShorthandProps = props => (
       that will be rendered.
     </p>
 
-    {codeExample([`<Button icon='chess rook' />`])}
+    {codeExample(`<Button icon='chess rook' />`)}
 
     <p>
       There are several forms of shorthand values that can be provided, but all of them share one
@@ -167,7 +159,7 @@ const ShorthandProps = props => (
       simply as that, as icon's name is not known at the moment {code('Button')} is rendered:
     </p>
 
-    {codeExample([`<Button icon={{ name: /* unknown yet */ undefined }} />`])}
+    {codeExample(`<Button icon={{ name: /* unknown yet */ undefined }} />`)}
 
     <p>
       It is quite common case that there is some component that is responsible for data fetching

From b293d4e9322aa82dfb9f2593e98081b6a5333b4f Mon Sep 17 00:00:00 2001
From: kuzhelov <kuroman@microsoft.com>
Date: Tue, 22 Jan 2019 11:46:24 +0100
Subject: [PATCH 11/11] refactor

---
 docs/src/components/CodeSnippet.tsx | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/docs/src/components/CodeSnippet.tsx b/docs/src/components/CodeSnippet.tsx
index 81e3e122e0..f58678f11c 100644
--- a/docs/src/components/CodeSnippet.tsx
+++ b/docs/src/components/CodeSnippet.tsx
@@ -11,12 +11,8 @@ export interface CodeSnippetProps {
   style?: React.CSSProperties
 }
 
-const joinToString = stringOrArray => {
-  if (typeof stringOrArray === 'string') {
-    return stringOrArray
-  }
-
-  return stringOrArray.join('\n')
+const joinToString = (stringOrArray: string | string[]) => {
+  return typeof stringOrArray === 'string' ? stringOrArray : stringOrArray.join('\n')
 }
 
 const formatters = {