MDSWC Base API

The MDSWCBase class accounts for common functionality that can be leveraged across all MDS web components. It extends HTMLElement and is in turn extended by all MDS web components.

Props

Prop	Type	Default	Description
`attributeChangedCallbackEnabled`	Boolean	`false`	Determines if the `attributeChangedCallback` should be suppressed or not.
`componentConnected`	Boolean	`false`	Determines if `connectedCallback()` has been called signaling that the element has inserted into the DOM.
`defaultProps`	Object	Props that were passed to the constructor	Stores the default props so they can be referenced later for slot overrides.
`firstSlotRender`	Object	`{}`	Stores an object that tracks if each existing slot has been already rendered once.
`hasSlotContent`	Object	`{}`	Stores an object that tracks if each existing slot has content.
`hasSlots`	Boolean	`undefined`	Determines if the component has slots.
`rendered`	Boolean	`false`	Determines if the component has been rendered or not.
`renderEnabled`	Boolean	`true`	Determines if the component render can be invoked.
`renderTimeout`	Number	`1000ms`	Stores the timeout value in milliseconds that determines how much time a component has available to render before the `componentRendered` `Promise` fails.
`state`	Object	`{}`	Object that stores the current key/value pairs for each of the props of the component.

Methods

The MDSWCBase class contains methods that are part of the native custom element lifecycle, instance methods that provide common base functionality, and static helper methods. All methods can further be classified as private or public depending on their intended use outside of the MDSWCBase class.

Status	Description
Private	Denotes an instance method that is used internally to MDSWC and should not be overwritten.
Public	Denotes a static helper method or instance method that can be invoked in components that extend `MDSWCBase`.

Native Custom Element Lifecycle Methods

The MDSWCBase class leverages a subset of the custom element lifecycle methods. These methods are used to track when an element has been inserted into the DOM and when changes to the element attributes occur.

Method Name	Type	Description
`attributeChangedCallback(attributeName, oldValue, newValue)`	Private	Called when an observed attribute has been added, removed, updated, or replaced. Also called for initial values when an element is created by the parser or upgraded. Note: Only attributes listed in the `observedAttributes` static getter method will receive this callback.
`connectedCallback`	Private	Called every time the element is inserted into the DOM.
`get observedAttributes`	Public	Static getter method defined on each custom element. It returns the element attributes which should be watched for changes.

Instance Methods

MDSWCBase contains several instance methods that provide common functionality to components which extend from MDSWCBase.

Method Name	Type	Description
`bindEventHandlers`	Public	Fallback method meant to be overwritten at the child component level.
`componentRendered`	Public	Returns a `Promise` that is resolved once the component is rendered. If the component is not rendered within the time constraint set by `this.renderTimeout`, the `Promise` will be rejected with an error message.
`configurePropGettersAndSetters(props)`	Private	Configures a getter and setter for all defined props.
`get defaultSlotContent`	Private	Returns the default slot content. If no default slot content exists, it will return the Boolean value `false`.
`firstConnectedCallback`	Private	Invoked once from `connectedCallback` when the component is first injected into the DOM.
`hasDefaultSlotContent`	Public	Returns a Boolean value determined by the existence of default slot content.
`hasNamedSlotContent(slotName)`	Public	Returns a Boolean value determined by the existence of named slot content.
`initialPropValues`	Private	Returns an Object containing default and instance prop values. The default values are determined by the component, while the instance props are determined by values passed via HTML attributes.
`removeAttributeWithoutRendering (attributeName)`	Public	Suppresses the `attributeChangedCallback` before removing an attribute so that `render` is not invoked.
`render`	Public	Calls `renderTemplate` if the custom element has been inserted into the DOM and render is enabled.
`renderTemplate`	Private	A debounced method which renders the template and binds all events using the `bindEventHandlers` method. If slots exist, the rendering process is delegated to the `renderTemplateWithSlots` method.
`renderTemplateWithSlots`	Private	Retrieves a copy of the template from the child component and checks for the existence of slots. If default slot content or named slot content is detected, it evaluates that content against possible slot prop overrides and creates the appropriate nodes needed to render the content. Once all slot content is evaluated and created, it removes all children from the currently rendered custom element and renders the newly created template.
`setInitialComponentState`	Private	Assigns the initial component state to the `this.state` instance property. State is determined by merging instance prop values with default prop settings. Instance values will take precedence over default values. If an MWC Config is present, it will be merged and take precedence over instance and default values.
`setDefaultSlotContentPresence`	Private	Iterates through all the default and named slots and updates the `this.hasSlotContent` instance property with a key value pair. The key is determined by the slot name, and the value is a Boolean value determined by the existence of content for the specific slot being evaluated.
`setPropWithoutRendering(p, newValue)`	Public	Suppresses the render functionality while setting a new value for a property. All validation rules still apply on the set prop value.
`setAttributeWithoutRendering(a, newValue)`	Public	Suppresses the render functionality while setting a new value for an attribute.
`triggerEvent(eventName, detail = '', bubbles = true)`	Public	Creates and dispatches a `CustomEvent` based on the arguments passed.
`triggerPropTypeErrorMessage(propName, propValue, expectedPropType, actualPropType)`	Private	Composes and logs prop validation error messages based on the arguments it receives.
`validateAllProps`	Private	Iterates through all props and calls the `validateProp` method for each prop.
`validateProp(propName, currentValue)`	Private	Validates a prop against all validation rules (e.g., required, enum, type, custom validation) specified for it.
`validatePropType(propName, propValue, expectedPropType)`	Private	Validates that the prop value matches the specified prop type and returns a Boolean value.

Static Methods

MDSWCBase contains several static methods that are common utility functions used by multiple MDSWC components.

Method Name	Type	Description
`camelCase(string)`	Public	Takes a kebab-cased string like `lightsaber-color` and converts it to a camelCased string like `lightsaberColor`. Use to convert kebab-cased HTML attributes into camelCased JavaScript properties.
`generateRandomNumber(max = 1000000000000000)`	Public	Returns a generated random number between 0 and `max`. This number can be used to build unique default `id` for HTML templates.
`identifyPropType(prop)`	Public	Returns the data type of the prop passed to it. The data type will be one of: `number` `string`, `boolean`, `array`, or `object`.
`kebabCase(string)`	Public	Converts a camelCased string like `jediMaster` to a kebab-cased string like `jedi-master`. Use to convert camelCased JavaScript properties into kebab-cased HTML attributes.
`moveChildNodes(oldParent, newParent)`	Public	Given two nodes that contain child nodes, this method moves child nodes from oldParent to newParent.
`get propTypeErrorMessageArticles`	Public	Returns an object containing prop type to grammatical articles for more grammatically correct error messages. For example, `that prop is an array` vs. `that prop is a array`.
`defineCustomElement(tag, element)`	Public	Calls the customElements.define global method to register the element parameter as the passed tag name

Usage Examples

Extending from MDSWC Base:

class MyComponent extends MDSWCBase {
    static get defaultProps() {
        // List all props as camelCased object keys in alphabetical order
        return {
            myProp: {
                type: String, // type is required for all props
            }
        };
    }

    // Observe all attributes
    static get observedAttributes() {
        const attributes = Object.keys(MyComponent.defaultProps).map(p => MDSWCBase.kebabCase(p));
        return attributes;
    }

    // Pass props to the MDSWC Constructor
    constructor() {
        super(MyComponent.defaultProps);
    }

    // define the component template that MDSWC Base
    get template() {
        return `
            <div>
                <h1>${this.myProp}</h1>
            </div>
        `;
    }
}

Link Template