Skip to content

Commit 823e4b7

Browse files
broccolinibroccolini
authored
Merge pull request #383 from primer/popover
Add 'Popover' component
2 parents 19e684f + 4938e89 commit 823e4b7

File tree

9 files changed

+461
-1
lines changed

9 files changed

+461
-1
lines changed

‎modules/primer-css/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,8 @@
5555
"primer-tables": "1.4.1",
5656
"primer-tooltips": "1.4.1",
5757
"primer-truncate": "1.4.1",
58-
"primer-utilities": "4.8.1"
58+
"primer-utilities": "4.8.1",
59+
"primer-popover": "0.0.1"
5960
},
6061
"keywords": [
6162
"primer",

‎modules/primer-popover/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2017 GitHub Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎modules/primer-popover/README.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Primer CSS Popover
2+
3+
[![npm version](http://img.shields.io/npm/v/primer-popover.svg)](https://www.npmjs.org/package/primer-popover)
4+
[![Build Status](https://travis-ci.org/primer/primer-css.svg?branch=master)](https://travis-ci.org/primer/primer-css)
5+
6+
> Popover for suggesting, guiding, and bringing attention to specific UI elements on a page.
7+
8+
This repository is a module of the full [primer-css][primer-css] repository.
9+
10+
## Install
11+
12+
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-popover` with this command.
13+
14+
```
15+
$ npm install --save primer-popover
16+
```
17+
18+
## Usage
19+
20+
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.
21+
22+
```scss
23+
@import "primer-popover/index.scss";
24+
```
25+
26+
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._
27+
28+
## Build
29+
30+
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:
31+
32+
```
33+
$ npm run build
34+
```
35+
36+
## Documentation
37+
38+
<!-- %docs
39+
title: Popover
40+
status: Experimental
41+
-->
42+
43+
Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
44+
45+
{:toc}
46+
47+
Popover's consist of:
48+
49+
- The block element, `.Popover`, which simply positions its content absolutely atop other body content.
50+
- The child element, `.Popover-message`, which contains the markup for the intended messaging and the visual "caret."
51+
52+
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.
53+
54+
The `Popover-message` element also supports several modifiers, most of which position the caret differently:
55+
56+
- `.Popover-message--top` (default): Places the caret on the top edge of the message, horizontally centered.
57+
- `.Popover-message--bottom`: Places the caret on the bottom edge of the message, horizontally centered.
58+
- `.Popover-message--right`: Places the caret on the right edge of the message, vertically centered.
59+
- `.Popover-message--left`: Places the caret on the left edge of the message, vertically centered.
60+
61+
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:
62+
63+
- `.Popover-message--top--right`
64+
- `.Popover-message--right--top`
65+
- `.Popover-message--bottom--left`
66+
- `.Popover-message--left--bottom`
67+
68+
Lastly, there is an added `.Popover-message--large` modifier, which assumes a slightly wider popover message on screens wider than 544px.
69+
70+
### Notes
71+
72+
The samples below include optional markup, like:
73+
- An outermost container that establishes stacking context (e.g. `position-relative`).
74+
- A choice piece of user interface (a button, in this case) to relate the popover to.
75+
- 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.
76+
77+
### Basic example
78+
Defaults to caret oriented top-center.
79+
80+
```html title="Default (top-center)"
81+
<div class="position-relative text-center">
82+
<button class="btn btn-primary">UI</button>
83+
<div class="Popover right-0 left-0">
84+
<div class="Popover-message text-left p-4 mt-2 mx-auto Box box-shadow-large">
85+
<h4 class="mb-2">Popover heading</h4>
86+
<p>Message about this particular piece of UI.</p>
87+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
88+
</div>
89+
</div>
90+
</div>
91+
```
92+
93+
### Large example
94+
95+
```html title="Large"
96+
<div class="position-relative text-center">
97+
<button class="btn btn-primary">UI</button>
98+
<div class="Popover right-0 left-0">
99+
<div class="Popover-message Popover-message--large text-left p-4 mt-2 Box box-shadow-large">
100+
<h4 class="mb-2">Popover heading</h4>
101+
<p>Message about this particular piece of UI.</p>
102+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
103+
</div>
104+
</div>
105+
</div>
106+
```
107+
108+
### Top-right-aligned example
109+
110+
```html title="Top-right"
111+
<div class="position-relative text-right">
112+
<button class="btn btn-primary">UI</button>
113+
<div class="Popover right-0">
114+
<div class="Popover-message Popover-message--top--right text-left p-4 mt-2 Box box-shadow-large">
115+
<h4 class="mb-2">Popover heading</h4>
116+
<p>Message about this particular piece of UI.</p>
117+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
118+
</div>
119+
</div>
120+
</div>
121+
```
122+
123+
### Top-right-aligned example
124+
125+
```html title="Top-left"
126+
<div class="position-relative">
127+
<button class="btn btn-primary">UI</button>
128+
<div class="Popover">
129+
<div class="Popover-message Popover-message--top--left p-4 mt-2 Box box-shadow-large">
130+
<h4 class="mb-2">Popover heading</h4>
131+
<p>Message about this particular piece of UI.</p>
132+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
133+
</div>
134+
</div>
135+
</div>
136+
```
137+
138+
### Right-aligned example
139+
140+
```html title="Right"
141+
<div class="Popover">
142+
<div class="Popover-message Popover-message--right p-4 mt-2 Box box-shadow-large">
143+
<h4 class="mb-2">Popover heading</h4>
144+
<p>Message about this particular piece of UI.</p>
145+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
146+
</div>
147+
</div>
148+
```
149+
150+
### Left-aligned example
151+
152+
```html title="Left"
153+
<div class="Popover">
154+
<div class="Popover-message Popover-message--left p-4 mt-2 Box box-shadow-large">
155+
<h4 class="mb-2">Popover heading</h4>
156+
<p>Message about this particular piece of UI.</p>
157+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
158+
</div>
159+
</div>
160+
```
161+
162+
### Bottom-aligned example
163+
164+
```html title="Bottom"
165+
<div class="Popover">
166+
<div class="Popover-message Popover-message--bottom p-4 mt-2 mx-auto Box box-shadow-large">
167+
<h4 class="mb-2">Popover heading</h4>
168+
<p>Message about this particular piece of UI.</p>
169+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
170+
</div>
171+
</div>
172+
```
173+
174+
### Bottom-right-aligned example
175+
176+
```html title="Bottom-right"
177+
<div class="Popover">
178+
<div class="Popover-message Popover-message--bottom--right p-4 mt-2 mx-auto Box box-shadow-large">
179+
<h4 class="mb-2">Popover heading</h4>
180+
<p>Message about this particular piece of UI.</p>
181+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
182+
</div>
183+
</div>
184+
```
185+
186+
### Bottom-left-aligned example
187+
188+
```html title="Bottom-left"
189+
<div class="Popover">
190+
<div class="Popover-message Popover-message--bottom--left p-4 mt-2 mx-auto Box box-shadow-large">
191+
<h4 class="mb-2">Popover heading</h4>
192+
<p>Message about this particular piece of UI.</p>
193+
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
194+
</div>
195+
</div>
196+
```
197+
198+
<!-- %enddocs -->
199+
200+
## License
201+
202+
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
203+
204+
[primer-css]: https://github.com/primer/primer
205+
[docs]: http://primercss.io/
206+
[npm]: https://www.npmjs.com/
207+
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
208+
[sass]: http://sass-lang.com/

‎modules/primer-popover/index.scss‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
// support files
2+
@import "primer-support/index.scss";
3+
@import "./lib/popover.scss";

0 commit comments

Comments
 (0)