@ewc-lib/ewc-dialog

EWC Dialog Component

Overview

The EWC Dialog component provides a standardized modal dialog for Eurostat web applications. It offers a consistent visual identity across Eurostat digital products while allowing for customization to meet specific application needs.

Features

• Responsive design that adapts to different screen sizes
• Customizable title, content (scrollable in main area) and non-scrollable footer (e.g. buttons)
• Tab-Focus trap, keeping focus within the dialog
• Accessibility compliant

Screenshot

API

Properties and Attributes

Property	Attribute	Type	Default	Description
visible		Boolean	false	true to show modally, false to hide
width	width	Boolean	90%	width of the dialog, preferrably in %. Default = 90%
maxWidth	maxWidth	Boolean	1200px	maximal width of the dialog
dismissable	dismissable	Boolean	false	if true, allows closing by clicking outside of the dialog's area
title		HTMLTemplateElement	null	HTMLTemplateElement containing HTML which is displayed as dialog title
scrollableContent		HTMLTemplateElement	null	HTMLTemplateElement containing HTML which is displayed in dialog's area for scrollable content
fixedContent		HTMLTemplateElement	null	HTMLTemplateElement containing HTML which is displayed in dialog's area for fixed content

Note:

All attribs and props support modification at runtime.

Please see the screenshot above to see where scrollable-content and fixed-content are displayed within the dialog box.

Usage

Installation

npm install @ewc-lib/ewc-dialog

Import the component in your application:

// Using ES modules
import "@ewc-lib/ewc-css-common/custom-props.css"
import "@ewc-lib/ewc-dialog"

Note about ewc-css-common

• "ewc-css-common/custom-props.css" is necessary and downloaded along with ewc-dialog.
• It needs to be imported by the host project because it's not imported by ewc-dialog itself.

Setting the content

HTML-content can be set in either of two ways:

• via HTML
• at runtime from JS using a setter

There are the following slots to set the respective content:

• title
  • appears in header
• scrollableContent
  • main content appearing in the middle
• fixedContent
  • appears at the bottom

Please see the usage-example/ directory, which contains working examples of setting the 3 different content slots in both ways, via HTML or JS.

Note: The term "slot" used here refers to an alternative implementation of the standard shadow-DOM slot mechanism. The content becomes actually part of this component's shadow DOM.

Note: fixedContent can be omitted - the space is taken up by scrollableContent in that case.

Example: set content via HTML

This is done by setting one of the three attributes on a HTMLTemplateElement (which is a child of ewc-dialog) to indicate the content:

• data-title
• data-scrollable-content
• data-fixed-content

Example:

<ewc-dialog>
  <template data-title><span>Title appears here</span></template>

  <template data-scrollable-content>
    <span>This is the where scrollable content appears - e.g. a longer text w/ explaining something.</span>
  </template>

  <template data-fixed-content>
    <span>This is the where fixed content appears. For example, a checkbox or buttons.</span>
  </template>
</ewc-dialog>

Example: set content via setter

const scrollableContent = document.createElement('template');
scrollableContent.innerHTML = ...
myDialog.scrollableContent = scrollableContent

// similar for title and fixed content

Arias of the dialog-HTML element

The dialog has 2 aria attributes:

<dialog aria-labelledby="title" aria-describedby="ariaDescription">

• If any child element (provided by the developer) has id="ariaDescription", the content of that element is being used to describe the dialog-HTML.
• The title (provided by the developer) gets the id="title" attribute automatically, in order to be referenced by aria-labelledby.

Tab-focus trap

This component supports a focus trap, with which the tab focus remains within the dialog box, meaning that it cycles through all tab-able elements and doesn't ever leave the dialog box.

If scrollableContent or fixedContent contains elements which should be included in the focus trap - for example links - there's the possibility to set the focus trap's last element (to the last focusable element in either scrollableContent or fixedContent) - after which the first element (the close button) is focussed again, thereby completing a cycle.

This is done by setting the attribute data-last-element approprietly.

Example:

...
const scrollableContent = document.createElement('template');
...
scrollableContent.innerHTML = `<a data-last-element href="https://ec.europa.eu/eurostat" title="Link to Estat">Some Link Text</a>`
...

This way, the focus remains trapped within the dialog - but also includes all tab-focusable elements within scrollableContent and/or fixedContent.

Note: The usage-example/ directory contains a working example of this.

Notes

Accessibility

The component is designed with accessibility in mind:

• Proper semantic HTML structure (dialog and header elements)
• Keyboard navigable elements
• Sufficient color contrast
• Screen reader friendly with appropriate ARIA attributes

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

European Union Public License (EUPL)

Changelog

• 3.2.2-beta

  • improve integration support

• 3.2.1-beta

  • fix: avoid double customElements.define() invocation when deriving classes

• 3.2.0-beta

  • a11y: remove autofocus, ARIAs
  • potential bugfix (move code out of constructor)

• 3.1.0-beta

  • feature: introduce configuration "dismissable" (close on click outside of dialog)
  • restructure docu

• 3.0.6-beta

  • feature: max width configuration for flexible adaption (to more/less text and wider/narrower width)

• 3.0.5-alpha

  • update usage examples

• 3.0.4-alpha

  • update usage examples

• 3.0.3-alpha

  • expose focus trap (for access from deriving classes)

• 3.0.2-alpha

  • support content change at runtime

• 3.0.1-alpha

  • isolate content from light-DOM styles

• 3.0.0-alpha

  • introduce shadow DOM
  • inline CSS (remove dependency to ewc-css)