# ldcover

vanilla popup / dialog library.


## Usage

install with npm:

    npm install ldcover

include required files ( `index.js` and `index.css` ), and create a ldcover object:

    var ldcv = new ldcover({ ... });


## Constructor Options

 - `root`: container.
   - you can use `template` tag as root for better performance during initialization. The first child in the template will be used as the real root for this ldcover.
 - `type`: additional class to add. default: ''. space seprated.
 - `transform-fix`: true/false. default: false.
   add a 'shown' class after ldcover is shown, which removes transform from .inner block.
   useful when content is blurred due to transform, but might lead to glitches when doing transition. use it carefully.
 - `delay`: milliseconds. default 300. should be aligned with transition duration. use to control 'shown' and 'running' classes.
 - `autoZ`: update root's z-index automatically. default true.
 - `baseZ`: the minimal z-index of root. default 3000.
   - with autoZ, ldcover keeps track of all cover' z-index and always use larger z-index for newly toggled covers.
     baseZ is then used as a base value for all autoZ covers.
     however, this may conflict with customized zmgr.
 - `zmgr`: set z-index manager for this cover.
   - `baseZ` will be used to call zmgr, which set a lower bound of `z-index`.
     set `baseZ` to 0 for zmgr to correct work with lower values.
 - `animation`: optional space separated class list.
   - will be added to .inner node when toggling on, and removed when toggling off.
   - handy for adding customized animation from libraries like transition.css or animate.css.
 - `escape`: should pressing escape key close the dialog. boolean, default true, optional.
 - `lock`: default false. if set to true, only API or data-ldcv-set could close this modal.
 - `resident`: default false. if set to true, DOM for this cover will always attached under document. otherwise false.
   - not resident node will be attached under `container` or document.body.
 - `inPlace`: default true. if set to false, root will be removed from original parent and re-added under body.
 - `container`: container for non-resident cover. by default parent of DOM or document.body
   - by default, non-resident cover is inserted to the location we find it. Set `container` to change this behavior.
     - when `container` is null, `root` is appended at the end of `document.body` when toggled.
     - otherwise, `root`is appended at the end of `container` when toggled.


## Object Methods

 - `toggle(state, data)`: toggle on/off ldcover.
   - `data`: optional parameter, which will be sent in `data` event.
     - program that manages the content of this cover can use this data to update its content.
 - `get(data)`: toggle on ldcover and return a promise, which will only be resolved when ldcover.set is called.
   - `data`: see `toggle` above.
 - `set(v, hide=true)`: set value, which resolve promises from get, and hide ldcover if hide = true.
   - use `data-ldcv-set` on elements to automatically set value when elements are clicked.
 - `cancel(err, hide=true)`: reject promise returned by `get` with given error `err`.
   - a default `Error` object with `{name: 'lderror', id: 999}` will be used if `err` is omitted.
   - ldcover is hidden if `hide` = true. true by default.
   - use `data-ldcv-cancel` on elements to automatically cancel when clicked.
 - `on(event, cb)`: listen to certain event. evnets:
   - `toggle.on`: when ldcover is toggled on. may fired before shown.
   - `toggle.off`: when ldcover is toggled off. may fired before hidden.
   - `toggled.on`: when ldcover is toggled on. fired after shown.
   - `toggled.off`: when ldcover is toggled off. fired after hidden.
 - `isOn()`: is this modal active ( opened ). return true or false
 - `lock()`: lock this cover. ( can't be dismissed by escaping )
   - alternatively, you can lock cover by adding `data-lock="true"` attribute to cover root.
 - `root()`: get cover root node.
 - `zmgr(mgr)`: set z-index manager for this cover. return the zmgr used if `mgr` is omitted.
   - `baseZ` will be used to call zmgr, which set a lower bound of `z-index`.
     set `baseZ` to 0 for zmgr to correct work with lower values.
 - `append(node)`: insert `node` in the base node of this cover.
   - useful if this ldcover is created without root.
 - `destroy(opt)`: object destroyer. `opt` is an option object with following fields:
   - `removeNode`: should ldcover remove DOM of this cover. default false
     - by default, DOM of this cover will be inserted back in DOM after this ldcover object been destroyed.
     - to also wipe out the DOM element, set `removeNode` to true.


## Class Method

 - `zmgr(zmgr)`: set a shared z-index manager. useful to manager widget z-index globally.
   this manager should provide following methods:
   - `add(baseVal, size)`: return actual added value.
     - baseVal: hint value for the z-index we'd like to use
     - size: hint size about how large the object we added is
   - `remove(val)`: remove val ( returned by add ) from this manager.

   as described above, `baseZ` will be used to call zmgr, which set a lower bound of `z-index`.
   set `baseZ` to 0 in ldcover instance so zmgr can work correclty with lower values.


## Spec. and structure

A simple ldcover popup are built with following html structure:

 * .ldcv          - topmost, fullscreen container
   * .base        - control the overall size and position for this box ( could be omit )
     * .inner     - dialog container. constraint size. transition animation goes here


one can decorate ldcover widgets by adding classes over the outmost element. following classes are defined by default:

 * .ldcv.bare:
   - no covered bk.
   - custom position for .ldcv > .base
   - overflow: visible for .ldcv > .base > .inner (why?)
 * .ldcv.lg, .ldcv.md
   - different size of panel. instead of using this, you could also set size directly on .base element.
 * .ldcv.full - fullscreen modal.
 * .ldcv.full-sm, .ldcv.full-md, .ldcv.full-lg - conditional fullscreen modal. break point:
   - `sm`: < 576px
   - `md`: < 768px
   - `lg`: < 960px
 * .ldcv.light - light overlay bk
 * .ldcv.mini - non-blocking, float style dialog with following position available:
   - .ldcv.mini.left
   - .ldcv.mini.right
   - .ldcv.mini.top
   - .ldcv.mini.bottom
 * .ldcv.inline - inline cover. Won't affect local layout

 * centering
   - by default .base is centered with vertical-align + ::after pseudo class. instead you can choose different methods, described below:
   - .ldcv.margin-centered
     - center with margin: auto + left/right/top/bottom: 0 and position: absolute. need width/height to be provided.
   - .ldcv.transform-centered
     - with transform-center, .base is centered with left: 50%, top: 50% + transform: translate(-50%,-50%), which don't need width/height to be provided anymore.
     - NOTE: this might causes content to be blur, so use it carefully.

 * .ldcv.scroll:
   - add `scroll` class on the ldcv node when you expect the modal content to longer than a screen's height. It makes the modal scrollable by users.

 * .ldcv.autogap:
   - add `autogap` class on the ldcv node to automatically adjust cover padding and margin along with responsive scenario, with two additional classes:
   - `.outer-gap`: only apply margin style. Used alone without `autogap`
   - `.autogap.nested-gap`: apply padding style in nested div. Used along with `autogap`

 * alternative transition
   - you can use alternative transition by adding additional class in .ldcv, including following classes:
     - ldcv-scale
     - ldcv-zoom
     - ldcv-vortex
     - ldcv-slide-rtl
     - ldcv-slide-ltr
     - ldcv-slide-ttb
     - ldcv-slide-btt
     - ldcv-flip-h-left
     - ldcv-flip-h-right
     - ldcv-flip-v-top
     - ldcv-flip-v-bottom
     - ldcv-fade
   - example of setting a alternative transition:


    <div class="ldcv ldcv-scale"> ... </div>



## Action

Simple popup could be configured with automatically set invocation to resolve promises waited by get. use `data-ldcv-set` attribute on elements to indicate what values to be passed into set:

    <div class="ldcv">
      <button data-ldcv-set="1"> OK </button>
      <button data-ldcv-set="0"> Cancel </button>
    </div>

use get function to wait for the return value:

    ldcv.get!then -> if it == "1" => "OK" else "Cancel"


## Todo

 - implement all this nice transitional effect:
   - https://tympanus.net/Development/ModalWindowEffects/
   - https://tympanus.net/Development/PageTransitions/


## License

MIT