boundless-popover

1.1.0 • Public • Published

Popover

A popover is a type of Dialog that is meant to provide additional context to content (an "anchor") currently on-screen. Typically, a popover is spawned by interacting with the content it enriches and is dismissed by clicking or shifting focus to an alternate location.

Alignment options for the popover are designed to mirror compass directions:

       →       ←
      NNW  N  NNE
↓ WNW             ENE ↓
    W   ANCHOR    E
↑ WSW             ESE ↑
      SSW  S  SSE
       →       ←

The arrows indicate which way the popover will extend, e.g. → means the popover is aligned to the left edge and extends in that direction. Diagonal corners (NW, NE, SE, SW) are currently not supported.

<Popover
    anchor={document.querySelector('.some-anchor-element')}
    preset={Popover.preset.N}>
    My popover content!
</Popover>

Installation

npm i boundless-popover --save

Then use it like:

/** @jsx createElement */

import { createElement, PureComponent } from 'react';

import ArrowKeyNavigation from 'boundless-arrow-key-navigation';
import Button from 'boundless-button';
import Popover from 'boundless-popover';

export default class PopoverDemo extends PureComponent {
    state = {
        words: [ {
            word: 'transcendental',
            syllabicRepresentation: 'tran·scen·den·tal',
            type: 'adjective',
            primaryDefinition: '',
            secondaryDefinitions: [
                'of or relating to a spiritual or nonphysical realm',
                '(of a number, e.g., e or π) real but not a root of an algebraic equation with rational roots',
            ],
        }, {
            word: 'obstetrics',
            syllabicRepresentation: 'ob·stet·rics',
            type: 'noun',
            preset: Popover.preset.N,
            primaryDefinition: 'the branch of medicine and surgery concerned with childbirth and the care of women giving birth',
            secondaryDefinitions: [],
        }, {
            word: 'olio',
            syllabicRepresentation: 'o·li·o',
            type: 'noun',
            preset: Popover.preset.E,
            primaryDefinition: [
                <span key='1'>another term for </span>,
                <a key='2' href='https://www.google.com/search?safe=active&espv=2&biw=1440&bih=74&q=define+olla+podrida&sa=X&ved=0CB8QgCswAGoVChMIlbiutZmDxwIVQx0-Ch1f-g9t'>olla podrida</a>,
            ],
            secondaryDefinitions: [
                'a miscellaneous collection of things',
                'a variety act or show',
            ],
        }, {
            word: 'anastrophe',
            syllabicRepresentation: 'a·nas·tro·phe',
            type: 'noun',
            preset: Popover.preset.W,
            primaryDefinition: 'the inversion of the usual order of words or clauses',
            secondaryDefinitions: [],
        }, {
            word: 'octothorp',
            syllabicRepresentation: 'oc·to·thorp',
            type: 'noun',
            preset: Popover.preset.WNW,
            primaryDefinition: 'another term for the pound sign (#)',
            secondaryDefinitions: [],
        } ],
    }

    handleKeyDown(index, event) {
        if (event.key === 'Enter') {
            this[this.state['showPopover' + index] ? 'showPopover' : 'hidePopover'](index, event);
        }
    }

    openPopover(index) {
        this.setState({ ['showPopover' + index]: true });
    }

    closePopover(index) {
        this.setState({ ['showPopover' + index]: false });
    }

    renderSecondaryDefinitions(definitions = []) {
        return definitions.length ? (
            <ArrowKeyNavigation component='ol'>
                {definitions.map((definition, index) => <li key={index}>{definition}</li>)}
            </ArrowKeyNavigation>
        ) : null;
    }

    renderPrimaryDefinition(definition) {
        return definition ? (<p>{definition}</p>) : null;
    }

    renderBody(definition) {
        return (
            <div>
                <strong>{definition.syllabicRepresentation}</strong>
                <br />
                <em>{definition.type}</em>
                {this.renderPrimaryDefinition(definition.primaryDefinition)}
                {this.renderSecondaryDefinitions(definition.secondaryDefinitions)}
            </div>
        );
    }

    renderPopovers() {
        return this.state.words.map((definition, index) => {
            return this.state['showPopover' + index] ? (
                <Popover
                    key={definition.word}
                    anchor={this.refs[`$word${index}`]}
                    caretAnchor={this.refs[`$word-caret-anchor${index}`]}
                    className='demo-popover'
                    closeOnOutsideFocus={true}
                    preset={definition.preset}
                    onClose={() => this.closePopover(index)}>
                    {this.renderBody(definition)}
                </Popover>
            ) : undefined;
        });
    }

    render() {
        return (
            <div>
                <p>
                    Words of the day for {(new Date()).toLocaleDateString()}:<br />
                    <sub>Note that the words with ⓘ symbols have their caret anchored to the symbol, rather than the center of the button.</sub>
                </p>

                <div className='spread'>
                    {this.state.words.map((definition, index) => {
                        return (
                            <Button
                                key={definition.word}
                                ref={`$word${index}`}
                                className='show-help-popover'
                                onPressed={() => this.openPopover(index)}
                                pressed={this.state[`showPopover${index}`]}
                                tabIndex='0'>
                                {definition.word} {index % 2 === 0 ? <span ref={`$word-caret-anchor${index}`}></span> : null}
                            </Button>
                        );
                    })}
                </div>

                {this.renderPopovers()}
            </div>
        );
    }
}

Popover can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { Popover } from 'boundless';

Props

Note: only top-level props are in the README, for the full list check out the website.

Required Props

  • anchor · a DOM element or React reference (ref) to one for positioning purposes

    Expects Default Value
    HTMLElement or object undefined

Optional Props

  • * · any React-supported attribute

    Expects Default Value
    any n/a
  • after · arbitrary content to be rendered after the dialog in the DOM

    Expects Default Value
    any renderable null
  • autoReposition · if the given alignment settings would take the popover out of bounds, change the alignment as necessary to remain in the viewport

    Expects Default Value
    bool true
  • before · arbitrary content to be rendered before the dialog in the DOM

    Expects Default Value
    any renderable null
  • captureFocus · determines if focus is allowed to move away from the dialog

    Expects Default Value
    bool true
  • caretAnchor · a DOM element or React reference (ref) to one for positioning purposes, the caret component will be automatically positioned to center on this provided anchor; by default it will center on props.anchor

    Expects Default Value
    HTMLElement or object undefined
  • caretComponent · the JSX that is rendered and used to point at the middle of the anchor element and indicate the context of the popover

    Expects Default Value
    ReactElement <svg viewBox='0 0 14 9.5' xmlns='http://www.w3.org/2000/svg'> <g> <polygon className='b-popover-caret-border' fill='#000' points='7 0 14 10 0 10' /> <polygon className='b-popover-caret-fill' fill='#FFF' points='6.98230444 1.75 12.75 10 1.25 10' /> </g></svg>
  • closeOnEscKey · enable detection of "Escape" keypresses to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

    Expects Default Value
    bool or function false
  • closeOnInsideClick · enable detection of clicks inside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

    Expects Default Value
    bool or function false
  • closeOnOutsideClick · enable detection of clicks outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

    Expects Default Value
    bool or function false
  • closeOnOutsideFocus · enable detection of focus outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

    Expects Default Value
    bool or function false
  • closeOnOutsideScroll · enable detection of scroll and mousewheel events outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

    Expects Default Value
    bool or function false
  • component · override the type of .b-dialog-wrapper HTML element

    Expects Default Value
    string 'div'
  • dialogComponent · override the type of .b-dialog HTML element

    Expects Default Value
    string 'div'
  • dialogProps

    Expects Default Value
    object {}
  • onClose · a custom event handler that is called to indicate that the dialog should be unrendered by its parent; the event occurs if one or more of the "closeOn" props (closeOnEscKey, closeOnOutsideClick, etc.) are passed as true and the dismissal criteria are satisfied

    Expects Default Value
    function () => {}
  • portalProps

    Expects Default Value
    object {}
  • preset · example:

    <Popover
        anchor={document.querySelector('.some-anchor-element')}
        preset={Popover.preset.NNE}>
        My popover content!
    </Popover>
    Expects Default Value
    Popover.preset.NNW or Popover.preset.N or Popover.preset.NNE or Popover.preset.ENE or Popover.preset.E or Popover.preset.ESE or Popover.preset.SSE or Popover.preset.S or Popover.preset.SSW or Popover.preset.WSW or Popover.preset.W or Popover.preset.WNW Popover.preset.S

Reference Styles

Stylus

You can see what variables are available to override in variables.styl.

// Redefine any variables as desired, e.g:
color-accent = royalblue

// Bring in the component styles; they will be autoconfigured based on the above
@require "node_modules/boundless-popover/style"

CSS

If desired, a precompiled plain CSS stylesheet is available for customization at /build/style.css, based on Boundless's default variables.

Package Sidebar

Install

npm i boundless-popover

Weekly Downloads

4

Version

1.1.0

License

MIT

Last publish

Collaborators

  • sighrobot