JavaScript in MDS

Web Components

What is an MDS Web Component?

MDS Web Components (MDSWC) are a translation of MDS HTML & CSS UI components into JavaScript-framework compatible functional components. Web Components are written in vanilla JavaScript and available as custom HTML elements. Every Web Component will:

• Be compatible with all JavaScript frameworks, including Vue.js, React, and Angular
• Conform to the Morningstar Web Components (MWC) specifications for Logging, Labeling, Formatting, and Configuration

MDS Web Components combine aspects from three existing initiatives: the W3C Web Component platform APIs, the Morningstar Web Component specifications, and the styles and markup from the Morningstar Design System.

These three initiatives are combined using vanilla JavaScript classes to define custom HTML elements that can be used alongside native HTML elements like <div>, <p>, and <a>.

Where Does MWC Fit?

The MDS team is working closely with the Morningstar Web Components (MWC) team to ensure components are built to fully comply with the MWC specifications. These Morningstar-designed specifications provide a standardized contract for configuration, internationalization, localization, and logging. Using MDS Web Components does not require MWC usage.

If your product has internationalization or localization requirements or you want a centralized method for configuration and logging then you need to use the MWC specifications. MDS Web Components have been built for easy compatibility with the MWC spec.

Why Vanilla JavaScript?

While custom elements can be built using popular JavaScript frameworks, like Vue and React, we chose to write the MDS web components in vanilla JavaScript to limit dependencies and potential framework version conflicts. This approach was vetted with the MDS JS working group and deemed the best way to support the array of frameworks used across Morningstar products.

Using Web Components

See the Getting Started for Engineers page for more details on installing and consuming MDS web components.

• Track the availability of web components across the MDS UI Component library on the component status page.
• API documentation for available web components, including prop tables, available slots, and custom events and methods, is found on component documentation pages.
• Components that are available as a web component provide a control to toggle variation examples between HTML markup and web component custom element markup.

Documentation Demo JavaScript

For UI components unavailable as a web component, when functionality can’t be achieved through HTML and CSS alone, MDS doc site pages—like those for Notifications, Dialogs, and Modals— may include JavaScript to illustrate functionality. This JavaScript is included for example purposes only, is not included in the MDS NPM package, and should never be used in production code. MDS adopting teams may reference these examples to write their own JavaScript for their products.

Using Third-Party Libraries in Components

MDS strives to minimize third-party dependencies in UI components. Third-party JavaScript libraries can be used if they provide significant functionality that cannot be articulated using demo JS and enable markup customization so that CSS classes and HTML structure align with BEM naming conventions for MDS.

Consider the following points when choosing between third-party libraries:

• Popularity — Popular libraries are often used by Morningstar product teams. Consult with product teams to determine what libraries are already being used.
• Actively Maintained — Look for a library with recent and frequent code commits that indicate the library is actively maintained.
• Accessibility — If the library controls markup that should contain accessibility attributes or features, make sure that it’s meeting those accessibility guidelines. For example, noUISlider added accessibility support in v10.0.0.

Installing Third-Party Libraries

1. Install third-party libraries via NPM using the --save flag to add them to MDS’s package.json file.
2. Copy the dependency file paths to the dependencies:copy gulp task found in gulpfile.js. This will copy them to the doc site’s asset path.