Add 'Popover' component

[brandonrosage]

This PR adds a new 'Popover' component, intended to suggest, guide, or bring attention to specific user interface elements on a page.

When present, it looks like this:

It's intended to establish a generalized, product-wide pattern from a convention that's used on github/github as a "TutorialPopover."

It's includes a small amount of unique CSS that adds a caret to a container (presumably one that uses the .Box component) and positions itself relative to a parent container. By default, it does so center-aligned. But with modifiers, it can also be left-aligned (.Popover-message--left), right-aligned (.Popover-message--right), and be assigned a larger width (.Popover-message--lg).

It assumes a context in which a relatively-positioned parent container includes:

• The UI element that the 'Popover' will bring attention to.
• An absolutely-positioned container for the 'Popover', which uses utility classes to offer flexibility with regard to the exact alignment of things.

<div class="position-relative text-center">

  <button class="btn btn-primary">UI</button>

  <div class="Popover right-0 left-0 text-left">
    <div class="Popover-message p-4 mt-2 Box box-shadow-large">
      <h4 class="mb-2">Popover heading</h4>
      <p>Message about this particular piece of UI.</p>
      <button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
    </div>
  </div>

</div>

It does not currently leverage any JavaScript to handle interaction with the nested button (e.g. "Got it!"), which would typically hide, remove, or dismiss the Popover.

/cc @primer/ds-core

[broccolini]

Left a few comments but as you said you are making some more changes I'll stop for now. Let me know when you're ready for a review later!

[broccolini]

Use $border-fade-black instead of the static value here.

[broccolini]

Use variables instead of static values here: $spacer-2 $border-style transparent.

[broccolini]

Use $border-style instead of solid here.

[broccolini]

Can you remove the / we don't use that on the other readme's.

[broccolini]

The border slightly overlaps into the Box area. I tweaked this in inspector (so let me know if I'm missing something) and changing ::before to top: -16px (or even better use $spacer-3) and the ::after to -14px gets rid of the overlap. Because of the alpha transparency on the border you see slightly darker points where the border overlaps but it's barely visible and acceptable to me. Happy to explore a non alpha transparent border option for things like this though.

Before

After

[broccolini]

Using a button here made me want to click on it to show/hide the popover because it kind of looks like a dropdown. Might be better to change this to a gray box with text along the lines of "New feature you want to draw attention to".

[brandonrosage]

@broccolini: Just pushed some changes that include the flexibility needed to accommodate github/github, and address some of your initial feedback.

The big change here is that I've added support for modifiers to .Popover-message that orient the caret in any of three locations on any of the four sides of the popover. So:

• .Popover-message (defaults to top-center)
• .Popover-message--top--right
• .Popover-message--top--left
• .Popover-message--bottom
• .Popover-message--bottom--right
• .Popover-message--bottom--left
• .Popover-message--right
• .Popover-message--right--top
• .Popover-message--right--bottom
• .Popover-message--left
• .Popover-message--bottom--top
• .Popover-message--bottom--bottom

Storybook demonstrates nearly all of these.

The catalyst for this addition was the variety of locations within a layout where github/github uses Popovers, which called for the caret to be on the top edge of the popover, the left edge, and sometimes in different orientations along that edge. Rather than break their layout, I built in this flexibility so folks could more easily "design" the orientation of their Popover in what are often tight spaces.

[brandonrosage]

@broccolini: I addressed the caret pixels for ya. Good to go?

[broccolini]

A couple of minor changes.

Biggest question I have is whether this should work with Box, be a modifier of box (there are some similar modifiers in github/github for Box--overlay), or if we should build in the background, border, and box shadow into this component. As it is currently, we'd need to add primer-box as a peer dependency since you can't fully create the component without.Box.

Since this is how it's currently being used in dotcom I'm not worried about including that change in this pr (though we should add the PeerDependency), we can keep this as Experimental status and v0.0.1 and follow up in a minor release.

cc @sophshep @jonrohan for second opinions on this.

[broccolini]

Use $border-black-fade instead of the static value.

[broccolini]

Use -$spacer-3 and $border-black-fade instead of the static values.

[broccolini]

Use -$spacer-3 and $border-black-fade instead of the static values.

[broccolini]

Use -$spacer-3 and $border-black-fade instead of the static values.

[broccolini]

How is this being used? In the docs it says it's a slightly larger option, but that's wrapped in a media query and not mentioned. If it's about the width and not the breakpoint, we should say --large. Also I'd prefer this was divisible by 8 as well—does it work at 320px?

[broccolini]

Use $spacer-4 instead of the static value.

[broccolini]

Use $spacer-4 instead of the static value.

[broccolini]

Use $spacer-4 instead of the static value.

[broccolini]

I'd like to make this an even number, suggest making this 232px or 24px—something divisible by 8px because that's what our spacing scale is based on. I know you based this on the original custom code, let me know if you this would cause issues, if so, we can adjust in a follow-up relelase.

[broccolini]

Thanks @brandonrosage! 💖

I'm not going to approve until after we update the peer dependency update, which I will do either tonight or tomorrow morning. But otherwise I think this is good to go

[broccolini]

👍