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, rootis 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:
  ...

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"

Dialog

promise-based dialog helpers as drop-in replacements for the browser native alert() / confirm() / prompt():

await ldcover.alert('hi');                  // resolves after OK is clicked
ok = await ldcover.confirm('are you sure?') // true ( OK ) / false ( cancel / escape )
name = await ldcover.prompt('your name?')   // string ( OK ) / null ( cancel / escape )

the first argument can be a message ( string / DOM node ) or an option object with msg inside; an additional option object can also be passed as the 2nd argument:

await ldcover.confirm({title: 'Delete', msg: 'are you sure?', danger: true});
await ldcover.confirm('are you sure?', {danger: true});  // same thing

common options for alert / confirm / prompt ( all optional ):

• title: dialog title.
• msg: message. plain text ( rendered with pre-wrap, so newlines work ) or a DOM node.
• okText: label of the OK button. default OK.
• cancelText: label of the cancel button. default Cancel.
• variant: variant of the OK option. default primary; use danger for destructive confirms. any string works - it lands as a semantic class on the button and is looked up in the theme's button map ( see Theming ).
• size: sm / md / lg. default md.
• cls: additional classes added on the .ldcv root, for theming.

i18n is left to the caller - pass localized okText / cancelText / msg yourself.

prompt additionally supports:

• placeholder: input placeholder.
• value: default value.
• type: input type. default text.
• isRequired: if true, OK won't resolve until the field is filled.

ldcover.dialog(opt)

generic method behind the helpers above. returns a Promise resolving {value, fields} where value is the value of the clicked option ( button ) and fields is an object of input values keyed by field name. closing by escape / backdrop click always resolves with value: null.

• title: optional title.
• msg: message. plain text ( pre-wrap ) or a DOM node.
• fields: optional input fields: [{name, label?, type='text', placeholder?, value?, isRequired?, error?, cls?}].
  • type: 'textarea' renders a textarea.
  • error: message shown when isRequired validation fails. default This field is required..
  • cls: additional classes added on the input / textarea element.
• options: buttons: [{label, value, variant?, focus?, novalidate?, action?, cls?}].
  • variant: semantic variant of this option, added as a class on the button in every theme. bundled ( styled by bundled themes ): default / primary / danger; any other string also works - style it yourself, or map it in your theme's button map.
  • focus: focused on open ( when no fields ); also triggered by Enter in input fields.
  • novalidate: skip required validation for this option. options with value: null ( cancel-ish ) skip validation automatically.
  • action: ({fields}) -> ... - clicking this option runs the callback and keeps the dialog open, instead of resolving. useful for opening nested dialogs or custom in-dialog behavior.
  • cls: additional classes added on the button element.
• escape: allow closing by escape key / backdrop click. default true.
• size: sm / md / lg.
• theme: visual theme, added as a class on the .ldcv root. bundled: default / bootstrap / generic. defaults to ldcover.dialog.theme() ( initially generic ). see Theming below.
• cls: additional classes added on the .ldcv root.

example:

ldcover.dialog({
  title: 'Rename',
  msg: 'enter a new name:',
  fields: [{name: 'name', isRequired: true}],
  options: [
    {label: 'Cancel', value: null},
    {label: 'Rename', value: 'ok', variant: 'primary', focus: true}
  ]
}).then(function(r) { if (r.value == 'ok') { console.log(r.fields.name); } });

dialogs can be stacked; z-index is managed by the same autoZ mechanism used by ldcover instances. each call builds its own cover, which is destroyed and removed from DOM automatically after dismissed.

Theming

structural styles ( layout / spacing / sizes ) always apply under .ldcv.builtin; all visual styles ( font size / color / background / border ) live in a separate theme class on the root, picked by the theme option:

• generic ( the default ): no visual styles at all. the dialog is structurally correct but unstyled - style it yourself via the class hooks below.
• default: bundled standalone look. neutral colors, no dependency.
• bootstrap: applies bootstrap's own classes onto the elements while building the dialog - form-control on inputs / textareas, btn btn-primary for OK, btn btn-outline-secondary for cancel, btn btn-danger for danger, is-invalid on inputs failing required validation. requires bootstrap css to be loaded on the page.

set a session-wide default once instead of passing theme on every call ( call with no argument to read it back ):

ldcover.dialog.theme('bootstrap');

themes that inject element classes ( like bootstrap ) are defined in the ldcover.dialog.themes registry - register your own for utility-css frameworks ( e.g. tailwind ):

ldcover.dialog.themes.tailwind = {
  input: 'border rounded px-3 py-2 w-full',
  textarea: 'border rounded px-3 py-2 w-full',
  invalid: 'border-red-500',
  error: 'text-red-600 text-sm',
  button: {
    "default": 'px-4 py-2 rounded border',
    primary: 'px-4 py-2 rounded bg-blue-600 text-white',
    danger: 'px-4 py-2 rounded bg-red-600 text-white'
  }
};
ldcover.dialog.theme('tailwind');

a theme entry may define title / msg / fields / field / label / input / textarea / error / options / button ( string, or a per-variant map ) / invalid ( toggled on inputs by required validation ).

the theme name also lands as a class on the .ldcv root ( .ldcv.builtin.my-theme ), so a custom theme can also just be visual css defined under it:

.ldcv.builtin        // dialog root; .sm / .md / .lg for size.
                     // .autogap and .scroll are also added by default,
                     // for rwd gapping and long-content scrolling
  .base .inner
    .title
    .msg             // pre-wrap
    .fields
      .field         // label + input/textarea + .error
                     // .has-error is added when required validation fails
    .options
      button         // with variant class: .default / .primary / .danger

the skeleton itself can also be replaced by overriding ldcover.dialog.dom, a function returning the root element of a dialog. keep the .base / .inner structure and the .title / .msg / .fields / .options hooks inside .inner; user provided content is applied onto the skeleton via DOM api ( no innerHTML ), so the skeleton should contain static markup only.

Todo

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

License

MIT