feat(docs): improve examples clarity and styling

[bmdalex]

Various improvements for the docs examples:

1. updated Editor to enable line numbers in JSX only
2. updated doc examples styles to have card look
3. updated example icons menu to include labels and removed extra buttons
4. updated Editor to show a preview of 4 lines only in JSX and HTML with a gradient look
5. added click handlers to toggle between active / readonly mode for JSX and HTML

Short demo

Screenshots:

1. Before:

2. After:

[codecov]

Codecov Report

Merging #62 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #62   +/-   ##
=======================================
  Coverage   69.72%   69.72%           
=======================================
  Files          70       70           
  Lines        1133     1133           
  Branches      194      215   +21     
=======================================
  Hits          790      790           
  Misses        338      338           
  Partials        5        5

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 07d3e9d...68e6992. Read the comment docs.

[levithomason]

Let's break this PR down to help move it forward:

1. Update Editor to enable line numbers in JSX
2. Update doc examples styles to have card look
3. Update example icon menu for better usability
4. Update Editor to show a preview of lines only

@alinais can you ensure these are tracked for us in the Doc Site requirement please?

[bmdalex]

@levithomason
@mnajdova
@kuzhelov
ready for review

[kuzhelov]

would like the following points being addressed before the merge (please, note that I've used Button examples running in Chrome, Mac OS for testing):

• there are quite a few examples where Click to edit overlaps the code. This problem seems to be critical to fix (it is quite simple to do that, actually, if we would avoid absolute positioning for this element)
  

---

Other issues are rather minor and more related to styling aspects - lets consider thoughts of other mates in these regards, will just point them out:

• not sure that we should use gradients in case when all other design aspects are made as flat - probably, we could place this 'click to edit' button at the top right corner of the code block, and provide shorter text to it (like 'Edit') - while using consistent flat design for it

• frankly, for me it seems not enough from examples separation point of view just to introduce margins between them. What seems to be more appealing is to introduce basic 'elevation' level for each example's card, so that it would be something like that before hover over (please, take a look on the border of the Default Button card - in contrast to the border of Emphasis Button that goes next)

and change to higher level of visual elevation on hover by making it more attractive to user:

---

• the last minor point is about margins of the example cards - seems that we should make them rather symmetric for both right and left sides. Currently these is no left margin provided to example card, and it looks a bit odd (please, notice left border alignment of the example card):

VS

[bmdalex]

@kuzhelov - thanks for reviewing, in reply to your comments:

there are quite a few examples where Click to edit overlaps the code. This problem seems to be critical to fix (it is quite simple to do that, actually, if we would avoid absolute positioning for this element)

both the way the gradients and the name of the label were the established requirement as per discussion with @levithomason ; I don't mind doing the changes as I don't have any strong preference here and to me it doesn't seem that different from user POV; @levithomason , what do u think?

frankly, for me it seems not enough from examples separation point of view just to introduce margins between them. What seems to be more appealing is to introduce basic 'elevation' level for each example's card, so that it would be something like that before hover over (please, take a look on the border of the Default Button card - in contrast to the border of Emphasis Button that goes next)

so you're saying we should add the hover behavior even when the user is not hovering? the change also includes a background color change from a previous PR

the last minor point is about margins of the example cards - seems that we should make them rather symmetric for both right and left sides. Currently these is no left margin provided to example card, and it looks a bit odd (please, notice left border alignment of the example card):

agreed, pushed a change to accomplish that
screenshot:

[kuzhelov]

so you're saying we should add the hover behavior even when the user is not hovering? the change also includes a background color change from a previous PR

actually, it sort of - the card should be visually separated from the other ones, and it is hard to achieve if we have a boundary built by white and light-grey colors. So, my suggestion was to apply box-shadow even for non-hovered-over state of the card, that would make visual effect of this card being elevated on top of the background just a slightly bit. After that, on hover, I've expected the card being 'elevated' more, with the shadow under card being spread broader.

Speaking of the first point - agree, lets sync up with @levithomason on that

[bmdalex]

actually, it sort of - the card should be visually separated from the other ones, and it is hard to achieve if we have a boundary built by white and light-grey colors. So, my suggestion was to apply box-shadow even for non-hovered-over state of the card, that would make visual effect of this card being elevated on top of the background just a slightly bit. After that, on hover, I've expected the card being 'elevated' more, with the shadow under card being spread broader.

got it; I have prepared a change with the following styles:

boxShadow: '0 0 15px #ccc',
...(isActive
  ? {
      boxShadow: '0 0 40px #aaa',
    }
  : isHovering && {
      boxShadow: '0 0 30px #aaa',
      zIndex: 1,
    }),

DEMO
what do you think, @kuzhelov @levithomason

[bmdalex]

Since @levithomason did not provide any input, I went with @kuzhelov 's suggestions and pushed a commit to address them

• changed JSX editor preview label Click to Edit -> Edit;
• moved the preview label under the code preview and increased height to make it more visible;
• improved the card style view by adding proper box-shadow

Here's updated:

• Short demo
• screenshot:
  

@kuzhelov - can you please take another look?

[kuzhelov]

please, introduce necessary changes to CHANGELOG.md - otherwise looks good to me 👍

[bmdalex]

Added equal padding and changes to CHANGELOG.md
Looks like you need to approve again, @kuzhelov ? thx!