1
1
mirror of https://github.com/primer/css.git synced 2024-12-13 06:38:07 +03:00
css/modules/primer-popover/README.md

228 lines
7.9 KiB
Markdown
Raw Normal View History

2017-11-09 20:41:18 +03:00
# Primer Popover
2017-10-26 23:31:29 +03:00
2017-11-15 21:08:26 +03:00
[![npm version](https://img.shields.io/npm/v/primer-popover.svg)](https://www.npmjs.org/package/primer-popover)
2017-11-09 20:41:18 +03:00
[![Build Status](https://travis-ci.org/primer/primer.svg?branch=master)](https://travis-ci.org/primer/primer)
2017-10-26 23:31:29 +03:00
> Popover for suggesting, guiding, and bringing attention to specific UI elements on a page.
2017-11-09 20:41:18 +03:00
This repository is a module of the full [primer][primer] repository.
2017-10-27 18:14:00 +03:00
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-popover` with this command.
```
$ npm install --save primer-popover
```
## Usage
The source files included are written in [Sass][sass] (SCSS) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
```scss
@import "primer-popover/index.scss";
```
You can also import specific portions of the module by importing those partials from the `/lib/` folder. _Make sure you import any requirements along with the modules._
## Build
For a compiled **CSS** version of this module, an npm script is included that will output a css version to `build/build.css` The built css file is also included in the npm package:
```
$ npm run build
```
2017-10-26 23:31:29 +03:00
## Documentation
<!-- %docs
title: Popover
2017-10-27 18:14:00 +03:00
status: Experimental
2017-10-26 23:31:29 +03:00
-->
2017-11-08 00:52:48 +03:00
Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
{:toc}
A popover consist of:
- The block element, `.Popover`, which simply positions its content absolutely atop other body content.
- The child element, `.Popover-message`, which contains the markup for the intended messaging and the visual "caret."
In the examples below, `Popover-message`, in particular, uses a handful of utility classes to style it appropriately. And these are intended to demonstrate the default, go-to presentation for the popover's message. By default, the message's caret is centered on the top edge of the message.
The `Popover-message` element also supports several modifiers, most of which position the caret differently:
- `.Popover-message--top` (default): Places the caret on the top edge of the message, horizontally centered.
- `.Popover-message--bottom`: Places the caret on the bottom edge of the message, horizontally centered.
- `.Popover-message--right`: Places the caret on the right edge of the message, vertically centered.
- `.Popover-message--left`: Places the caret on the left edge of the message, vertically centered.
Each of these modifiers also support a syntax for adjusting the positioning the caret to the right, left, top, or bottom of its respective edge. That syntax looks like:
- `.Popover-message--right-top`
- `.Popover-message--top-right`
- `.Popover-message--right-bottom`
- `.Popover-message--bottom-right`
- `.Popover-message--left-bottom`
- `.Popover-message--bottom-left`
- `.Popover-message--left-top`
- `.Popover-message--top-left`
2017-11-07 02:48:47 +03:00
Lastly, there is an added `.Popover-message--large` modifier, which assumes a slightly wider popover message on screens wider than 544px.
### Notes
The samples below include optional markup, like:
- An outermost container that establishes stacking context (e.g. `position-relative`).
- A choice piece of user interface (a button, in this case) to relate the popover to.
- Use of the `Details` and `js-details` family of class names, which interact with JavaScript to demonstrate dismissal of the popover by clicking the nested "Got it!" button.
2017-10-27 18:14:00 +03:00
### Basic example
Defaults to caret oriented top-center.
2017-10-27 18:14:00 +03:00
```html title="Default (top-center)"
2017-10-27 18:14:00 +03:00
<div class="position-relative text-center">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
<div class="Popover-message text-left p-4 mt-2 mx-auto Box box-shadow-large">
2017-10-27 18:14:00 +03:00
<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>
```
### Large example
2017-10-26 23:31:29 +03:00
```html title="Large"
<div class="position-relative text-center">
2017-10-27 18:14:00 +03:00
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
2017-11-07 02:48:47 +03:00
<div class="Popover-message Popover-message--large text-left p-4 mt-2 Box box-shadow-large">
2017-10-27 18:14:00 +03:00
<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>
```
2017-10-26 23:31:29 +03:00
### Top-right-aligned example
2017-10-26 23:31:29 +03:00
```html title="Top-right"
<div class="position-relative text-right">
2017-10-27 18:14:00 +03:00
<button class="btn btn-primary">UI</button>
<div class="Popover right-0">
<div class="Popover-message Popover-message--top-right text-left p-4 mt-2 Box box-shadow-large">
2017-10-27 18:14:00 +03:00
<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>
2017-10-26 23:31:29 +03:00
</div>
```
### Top-right-aligned example
```html title="Top-left"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--top-left 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>
```
### Right-aligned example
2017-10-27 18:14:00 +03:00
```html title="Right"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--right 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>
2017-10-27 18:14:00 +03:00
</div>
</div>
```
### Left-aligned example
```html title="Left"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--left 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>
```
### Bottom-aligned example
```html title="Bottom"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--bottom p-4 mt-2 mx-auto 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>
```
### Bottom-right-aligned example
```html title="Bottom-right"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--bottom-right p-4 mt-2 mx-auto 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>
```
### Bottom-left-aligned example
```html title="Bottom-left"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--bottom-left p-4 mt-2 mx-auto 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>
```
2017-10-26 23:31:29 +03:00
<!-- %enddocs -->
## License
2017-10-27 18:14:00 +03:00
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
2017-10-26 23:31:29 +03:00
2017-11-09 20:41:18 +03:00
[primer]: https://github.com/primer/primer
[docs]: http://primer.github.io/
2017-10-26 23:31:29 +03:00
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/