dropdown - Vaadin Add-on Directory
Polymer-based web component for a D2L dropdown
**[ This description is mirrored from README.md at [github.com/BrightspaceUI/dropdown](https://github.com//BrightspaceUI/dropdown/blob/v7.4.0/README.md) on 2019-05-22 ]**
**Looking for SASS-based `vui-dropdown`?** It's [over here](https://github.com/Brightspace/valence-ui-dropdown/tree/sass).
# d2l-dropdown
[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/BrightspaceUI/dropdown)
[![Bower version][bower-image]][bower-url]
[![Build status][ci-image]][ci-url]
A [Polymer](https://www.polymer-project.org)-based web component for dropdown/flyouts.
## Installation
`d2l-dropdown` can be installed from [Bower][bower-url]:
```shell
bower install d2l-dropdown
```
## Usage
Include the [webcomponents.js](http://webcomponents.org/polyfills/) "lite" polyfill (for browsers who don't natively support web components), then import the opener and content components as needed:
```html
```
### Dropdown Openers
#### Generic Opener
`d2l-dropdown` is a generic opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`) enabling alternate opener implementation using existing elements/components. Provide and indicate your own opener element with the class attribute value `d2l-dropdown-opener`. Wire-up is automatic.
```html
Some content...
```
If the dropdown is initially empty when it's opened, the dropdown pointer will not be positioned correctly. In such cases, the `no-auto-open` attribute may be added to the opener, enabling you to take control of when the dropdown is actually opened:
```html
...
```
```javascript
dropdown.addEventListener('click', function() {
// fetch some content
...
// take control of when the dropdown is actually opened
dropdown.toggleOpen();
});
```
#### Button Opener
`d2l-dropdown-button` is a `d2l-button` opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for the button and content component as needed.
```html
Some content...
```
* `primary` - optionally render button as primary button
#### Subtle Button Opener
`d2l-dropdown-button-subtle` is a `d2l-button-subtle` opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for the button and content component as needed.
```html
Some content...
```
#### Context Menu Opener
`d2l-dropdown-context-menu` is a simple/minimal opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for accessibility and content component as needed. Optionally, specify the `translucent` attribute for busy/rich backgrounds.
```html
Some content...
```
#### More Opener
`d2l-dropdown-more` is a simple/minimal opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for accessibility and content component as needed. Optionally, specify the `translucent` attribute for busy/rich backgrounds.
```html
Some content...
```
#### Visible on Ancestor Behavior
For busy/rich backgrounds, the `d2l-dropdown-more` and `d2l-dropdown-context-menu` openers support the [VisibleOnAncestorBehavior](https://github.com/Brightspace/d2l-polymer-behaviors-ui) that can be enabled by specifying the `visible-on-ancestor` attribute. See [VisibleOnAncestorBehavior](https://github.com/Brightspace/d2l-polymer-behaviors-ui) for more details on configuring that behavior.
```html
Some content...
```
### Dropdown Contents
#### Generic Content
`d2l-dropdown-content` is a generic container for dropdown content. It provides behavior such as sizing, positioning, and managing focus gain/loss.
```html
Google
```
* `min-width` (number) - optionally override default min-width
* `max-width` (number) - optionally override default max-width
* `no-auto-fit` - optionally opt out of auto-sizing
* `no-padding` - optionally render with no padding
* `no-pointer` - optionally render without a pointer
* `render-content` - optionally stamp contents into DOM immediately
* `vertical-offset` - optionally provide custom offset, positive or negative
* `align` (enum) - optionally align dropdown. Valid values are "start","end". If not set, the dropdown will attempt be centred
* `boundary` (object) - optionally provide boundaries to where the dropdown will appear. Valid properties are "above", "below", "left", "right"
```javascript
// triggered when dropdown opened
content.addEventListener('d2l-dropdown-open', () => { ... });
// triggered when dropdown closed
content.addEventListener('d2l-dropdown-close', () => { ... });
```
#### Menu Content
`d2l-dropdown-menu` is a container for a [d2l-menu](https://github.com/Brightspace/d2l-menu-ui) component. It provides behavior in addition to the basic behavior of `d2l-dropdown-content` such as closing the menu when menu items are selected, resetting to the root of nested menus when reopening, etc.
```html
```
## Developing, Testing and Contributing
After cloning the repo, run `npm install` to install dependencies.
If you don't have it already, install the [Polymer CLI](https://www.polymer-project.org/2.0/docs/tools/polymer-cli) globally:
```shell
npm install -g polymer-cli
```
To start a [local web server](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#serve) that hosts the demo page and tests:
```shell
polymer serve
```
To lint ([eslint](http://eslint.org/) and [Polymer lint](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#lint)):
```shell
npm run lint
```
To run unit tests locally using [Polymer test](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#tests):
```shell
npm run test:polymer:local
```
To lint AND run local unit tests:
```shell
npm test
```
[bower-url]: http://bower.io/search/?q=d2l-dropdown
[bower-image]: https://badge.fury.io/bo/d2l-dropdown.svg
[ci-url]: https://travis-ci.org/BrightspaceUI/dropdown
[ci-image]: https://travis-ci.org/BrightspaceUI/dropdown.svg?branch=master
## Versioning
Commits and PR merges to master will automatically do a minor version bump which will:
* Update the version in `package.json`
* Add a tag matching the new version
* Create a github release matching the new version
By using either **[increment major]** or **[increment patch]** notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
D2L