Percy examples combination - Examples.html improvements

[jmuzina]

Links in combined examples

While splitting the combined examples and working on the utilities combination, I noticed that it could become somewhat difficult to keep track of which example you are looking at when looking at bits of a combined example. If there were a problem with a combined example in a Percy snapshot, it would take a bit of work to determine which example the problem came from.

This PR updates the examples template to do the following for combined examples:

• Show the name of the current template in the example body with a link to the example
• Renders only the body inside embedded examples, rather than an entire HTML document (which would cause invalid markup)

Screenshot

Here's an example of how this will look, with the Notifications combined example.

Vertical spacing

Some combined examples (such as search & filter, context menu, navigation) have overlay/non-contained contents that can overlap other combined examples if we're not careful.

In my PRs so far I have been handling this case manually by creating multple divs with u-sv3 after examples that need extra space below them. However, this came to be tedious so I have come up with a (hopefully) more streamlined approach for this.

This does the following:

• Allows passing spacing_below into an example template. If spacing_below is defined and the example is a combined example, then a div with margin-bottom: <spacing_below>rem will be added below the block content to make space for whatever content is needed.

Example

Example usage, with Search & Filter

Markup

{% extends "_layouts/examples.html" %}
{% block title %}Search and filter / Combined{% endblock %}

{% block standalone_css %}patterns_search-and-filter{% endblock %}

{% block content %}
{% with is_combined = true %}
<section>{% include 'docs/examples/patterns/search-and-filter/chip-overflow.html' %}</section>
<section>{% include 'docs/examples/patterns/search-and-filter/default.html' %}</section>
<section>{% include 'docs/examples/patterns/search-and-filter/expanded.html' %}</section>
<section>
  {% with spacing_below = 17 %}
    {% include 'docs/examples/patterns/search-and-filter/with-chips.html' %}
  {% endwith %}
</section>
<section>{% include 'docs/examples/patterns/search-and-filter/with-search-prompt.html' %}</section>
{% endwith %}
{% endblock %}

Screenshot

[webteam-app]

Demo

Jenkins

demos.haus

[bartaz]

I generally like this, but it's worth noting that if/when browsers do change their text rendering methodology, the text on the page may cause visual regression test failures. Hopefully Percy is smart enough to ignore such minor changes.

If browsers change their text rendering methodology all of our visual tests will fail anyway, right?

[jmuzina]

@bartaz I rolled the changes we discussed to only embed the block content into this PR. Here's an example of how this looks:

card-combined.txt card-default.txt

[jmuzina]

Contents of #5176 have been merged into this PR for review simplicity's sake (PRs are being combined)