@momentum-ui/web-components 2.16.6 → 2.16.8

package/ANGULAR_USAGE.md

@@ -0,0 +1,102 @@
+# Usage With Angular (11)
+
+The following walk-through uses angular-cli my-app to quick start a simple usage scenario. Please read through, and adapt for your project's specific needs.
+
+### Create-react-app
+First and foremost, follow the instructions in order to get the angular my-app running locally.
+<https://angular.io/guide/setup-local>
+1. `npm install -g @angular/cli`
+2. `ng new my-app`
+3. `cd my-app`
+4. `ng serve --open`
+
+### Include Required Dependencies in package.json
+##### In package.json (`create-react-app/my-app/package.json`)
+Add peerDependencies & devDependencies to match the following: <br>
+<sub>*Note: at this point, only version `2.1.5-dev` works for "@momentum-ui/web-components" within an angular application.*</sub>
+  ```json
+  "peerDependencies": {
+    "@momentum-ui/core": "^19.9.12",
+    "@momentum-ui/icons": "^7.54.0",
+    "@momentum-ui/tokens": "^1.5.0",
+    "@momentum-ui/utils": "^6.2.7",
+    "@momentum-ui/web-components": "2.1.5-dev",
+    "lit-element": "^2.3.1",
+    "lit-html": "^1.2.1"
+  },
+  ```
+  
+  and add these to the `devDependencies`:
+
+  ```json
+    "@momentum-ui/core": "^19.9.12",
+    "@momentum-ui/icons": "^7.54.0",
+    "@momentum-ui/tokens": "^1.5.0",
+    "@momentum-ui/utils": "^6.2.7",
+    "@momentum-ui/web-components": "2.1.5-dev",
+    "lit-element": "2.3.1",
+    "lit-html": "1.2.1",
+  ```
+  <sub>*The changes to scripts commands enable the following Webpack modifications to be run within the Create React App environment. <br> The addition of `jest` as a resolution is important for tests to run*</sub>
+  
+### Add CUSTOM_ELEMENTS_SCHEMA
+##### In app.module.ts (`my-app/src/app/app.module.ts`)
+Update the file to match the following (line 1 and line 15 changed):
+```javascript=
+import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  imports: [
+    BrowserModule
+  ],
+  providers: [],
+  bootstrap: [AppComponent],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+})
+export class AppModule { }
+```
+
+### Modify tsconfig.json
+##### In tsconfig.json (`my-app/tsconfig.json`)
+Set esModuleInterop to true under compilerOptions
+```json
+  "compilerOptions": {
+    "esModuleInterop": true,
+```
+
+### Add a Web Components to your Project
+1. Add the following import:
+##### In app.component.ts (`my-app/src/app/app.component.ts`)
+```js
+  import '@momentum-ui/web-components';
+```
+OR import each individual web component
+```js
+  import '@momentum-ui/web-components/dist/comp/md-button';
+  import '@momentum-ui/web-components/dist/comp/md-icon';
+```
+<sub>*NOTE: You only need to import the web-components module at the top level of your application in order to use web components anywhere throughout.*
+</sub>
+
+2. Insert the following sample web component for testing purposes:
+##### In app.component.html (`my-app/src/app/app.component.html`)
+```html
+<md-theme>
+  <md-button variant="green"><md-icon slot="icon" name="play_16"></md-icon><span slot="text">Code On!</span></md-button>
+</md-theme>
+```
+<sub>*NOTE: You must wrap your application with the `<md-theme>` element. It provides a set of core style resets and CSS custom variables that provide Theme color tokens, among other things. You can test these by toggling attributes `lumos` and/or `darkTheme` on the `<md-theme>` element.*
+</sub>
+
+##### Now it is time to get your app running locally! <br>
+(within `my-app` directory)
+
+1. `yarn` installs all dependencies.
+2. `yarn build` copies the required static assets for fonts and icons.
+3. `yarn start` launches project locally.

package/APPLYING_STYLES.md

@@ -0,0 +1,44 @@
+# Contributing to Momentum UI Web Components
+
+Thank you for contributing to this library! This is a guide to properly connect your new component's modularized styles to utilize the efficiency and Shadow DOM support of Constructable Stylesheets.
+
+## IMPORTING EXISTING STYLES TO WEB COMPONENT
+
+Most components have existing style modules that were carried over from the Momentum Core SMACSS library. While they can be used directly with minimal setup, as we work on setting up Lumos and Web Component specific style changes, these steps will lead to a successful migration and refactor of styles in to our own SCSS library.
+
+1. Create a `scss` folder in the component's directory.
+2. If available, copy over the `module.scss`, `component-name.scss`, `mixins.scss` and `settings.scss` found in `src/momentum_scss/components/component-name/`, and paste them to `src/components/component-name/scss`. 
+3. Inside your `ComponentName.ts` file, import the scss file: `import styles from "./scss/module.scss";`
+4. Check the `@import` paths in `module.scss` to ensure successful compilation of styles.
+5. Webpack will compile the CSS for you, but in order to adopt the styles into your component, place this LitElement function before `render()` :
+
+```javascript
+static get styles():
+  return [styles]
+}
+```
+
+### USING COMMON RESETS TO SOLVE SHADOW DOM ISSUES
+
+In many cases, particularly within components whose child elements need box-position and typography styles, it is necessary to also adopt the basic normalize and reset styles provided by Momentum. Because styles cannot cross into new Shadow Roots, this needs to be done on most components. 
+
+1. Import the reset styles from `src/assets/styles/reset.scss`
+2. Add it to the start of the `CSSResultArray` in `getStyles()`, adopting them before others. 
+
+```javascript
+static get styles():
+  return [reset, styles]
+}
+```
+
+### EDITING AND ADDING NEW STYLES TO COMPONENTS
+
+By linking to the `momentum_scss` library we are referring to the legacy rulesets that render the older Momentum design look and is optomized for React applications. 
+
+New Lumos style updates will take place in the styles made local to the component files themselves, moving away from the convention of keeping component style markup inside the SMACSS library, and only keeping global settings and shared styles there.
+
+1. Begin edits within `component-name.scss`, and do not write any styles to `module.scss`. Find and replace selectors that rely upon old Momentum scss variables, for example `%#{button-class}` should become `.md-button`, making the code easier to read. Check existing style definitions and styles that do not exist in Lumos. For any new style you write, find existing selectors and style decorations to edit, and avoid writing overrides. 
+2. If any mixins associated with the component are never used, delete them from the local `mixins.scss` file. If a `settings.scss` file is present, remove unused and legacy variables that are not applicable to Lumos.
+3. Once component-specific modules are edited, remove the `@import`s of global scss modules from `momentum_scss` and replace with imports from `wc_scss`. Best practice is to have `yarn start` running and following the compile errors that appear in the console to identify the modules that have the right dependencies.
+4. If a scss module is not yet present in the `wc_scss` directory, copy it over from the `momentum_scss` following the familiar file structure, taking a moment to inspect it for irellevant legacy code, repition, or other bloat you can confidently delete.
+5. Once the `module.scss` file compiles successfully with the minimal imports needed, your component should render correctly with you new styles, and no longer depend on legacy style from the momentum_scss library!

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.9.0] - 2024-03-08
+
+### Commits
+
+- 973880b7f 2024-03-05 niti-owner: feat: Renamed role to ariaRole property (#1557)
+- 857a8615a 2024-03-04 Ruchi Priya: CX-10203 : fix(accessibility): correct dialog label for station credential (#1555)
+- a5ad95c2b 2024-03-01 Mithun.S: fix(accesibility): sortable table acessibility fix (#1554)
+- 51d251c13 2024-02-29 Ruchi Priya: fix(accessibilty): visual headings not announced as heading (#1550)
+- 4436c7072 2024-02-27 niti-owner: #feat: added arai label and role property for link component (#1551)
+- c2a4657a0 2024-02-27 Vinit Kumar: Added Error message in aria label based on props (#1548)
+
+### Updates
+
+- Renamed property role to ariaRole in md-link. (#1557)
+- Made ariaDescription Optional in md-modal. (#1555)
+- Accessibility fix in md-table-advanced on Sortable button (#1554)
+- Convert md-modal header from span to H2 (#1550)
+- Added role and ariaLabel in md-link (#1551)
+- Added id property in md-phone-input (#1548)

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+
+# Contributing
+
+We'd love for you to contribute to our source code and to make Momentum UI Web Component library even better than it is today! Below are the guidelines to follow.
+
+## Keep in touch with the team
+
+Either you are internal to Cisco or not, feel free to reach out to the repository admins to be added to the `Momentum UI Web Components Q&A` Webex Teams space. You will be able to ask questions, follow discussions and make sure more folks get to take a look at your PR by posting a link.
+
+## Adding new components
+
+If you wand to add new component to `src/components`:  
+
+1. Use unique html tag with `md-` prefix
+2. To register custom element, use `@customElementWithCheck("md-my-comp")` decorator instead of `@customElement("md-my-comp")` from "lit-element" framework
+
+    **Note**: `customElementWithCheck` will not throw error if "custom element" name is already registered by another component, so please make sure your new component name, e.g. `"md-my-comp"`, is not already being used by another component in this library.
+
+3. Wrap your component in a unique namespace, e.g.:
+    ```ts
+    export namespace Avatar {
+    export type Type = typeof AvatarType[number];
+
+    export type Size = typeof AvatarSize[number];
+
+    @customElementWithCheck("md-avatar")
+    export class ELEMENT extends LitElement {
+        ...
+    }
+
+    declare global {
+        interface HTMLElementTagNameMap {
+            "md-avatar": Avatar.ELEMENT;
+        }
+    }
+    ```
+    Make sure all component related types are defined withing the namespace scope. This way, they will be accessible to the library consumer when used in TypeScript environment.
+
+4. Keep in mind that we are supporting multiple themes that build on top of default Momentum CSS. This is manifested through the use of **Style Tokens** - you can find reference material in [Applying Styles](./APPLYING_STYLES.md).
+5. Last, but not least, make sure to:
+    * Add Unit Test coverage to new and existing components to maintain at least 80% coverage (We strive for at least 90%);
+    * Add Storybook component representation for each new component, as well as make sure to add any new feature to the existing component's Storybook `*.stories.ts` file.
+---
+### New component only
+We are using webpack chunk split functionality to minimize footprint of our library importing.  
+So you must register your component as a new chunk.  
+<br/>
+Please add entry and path to component source in `webpack.config.ts`:
+```js
+"comp/md-my-comp-entry": "./src/components/my-comp/MyComp",
+```
+to `commonDist.entry` section. 
+
+
+ 
+

package/REACT_USAGE.md

@@ -0,0 +1,145 @@
+# Usage With React
+
+The following walk-through uses create-react-app to quick start a simple usage scenario. Please read through, and adapt for your project's specific needs.
+
+### Create-react-app
+First and foremost, follow the instructions in order to get the create-react-app running locally.
+<https://github.com/facebook/create-react-app>
+1. `git clone https://github.com/facebook/create-react-app.git`
+2. `cd create-react-app`
+3. `yarn create react-app my-app`
+4. `cd my-app`
+5. `yarn start`
+
+### Include Required Dependencies in package.json
+##### In package.json (`create-react-app/my-app/package.json`)
+Add resolutions & devDependencies, then modify the scripts section to match the following: <br>
+  ```json
+  "resolutions": {
+    "lit-element": "2.3.1",
+    "lit-html": "1.2.1",
+    "jest": "26.6.0"
+  },
+  "devDependencies": {
+    "@momentum-ui/core": "^19.9.12",
+    "@momentum-ui/icons": "^7.54.0",
+    "@momentum-ui/tokens": "^1.5.0",
+    "@momentum-ui/utils": "^6.2.7",
+    "@momentum-ui/web-components": "2.1.2",
+    "copy-webpack-plugin": "^6.3.2",
+    "lit-element": "2.3.1",
+    "lit-html": "1.2.1",
+    "react-app-rewired": "^2.1.8"
+  },
+  "scripts": {
+    "start": "react-app-rewired start",
+    "build": "react-app-rewired build",
+    "test": "react-app-rewired test",
+    "eject": "react-scripts eject"
+  },
+  ```
+  <sub>*The changes to scripts commands enable the following Webpack modifications to be run within the Create React App environment. <br> The addition of `jest` as a resolution is important for tests to run*</sub>
+  
+### Copy Static Assets & Configure Jest for Testing
+Momentum Web Components use Cisco fonts and Icon fonts that must be served within the project. This Webpack ammendment copies those resources from the installed dependencies (`node_modules`) to the `public` directory. In addition, the jest config override ensures tests run successfully with the addition of web components.
+##### Create config-overrides.js (`create-react-app/my-app/config-overrides.js`)
+Copy the following code below:
+```js
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+const path = require('path');
+
+const hoistedModules = path.resolve("node_modules");
+const pPublic = path.resolve('public');
+
+module.exports = {
+  webpack: (config, env) => {
+    if (!config.plugins) {
+      config.plugins = [];
+    }
+
+    const copyWebpackPlugin = new CopyWebpackPlugin({
+    patterns: [
+      {
+        from: `${hoistedModules}/@momentum-ui/core/fonts`,
+        to: `${pPublic}/fonts`,
+      },
+
+      {
+        from: `${hoistedModules}/@momentum-ui/icons/fonts`,
+        to: `${pPublic}/fonts`,
+      },
+      
+      {
+        from: `${hoistedModules}/@momentum-ui/web-components/dist/assets/styles`,
+        to: `${pPublic}/css`,
+      },
+
+      {
+        from: `${hoistedModules}/@momentum-ui/icons/css/momentum-ui-icons.min.css`,
+        to: `${pPublic}/css`,
+      },
+    ],
+  });
+
+    config.plugins.push(copyWebpackPlugin);
+    return config;
+  },
+
+  jest: (config) => {
+    config.transformIgnorePatterns = [
+        "[/\\\\]node_modules/\\\\.+\\.(js|jsx|ts|tsx)$",
+        "^.+\\.module\\.(css|sass|scss)$"
+    ];
+    return config;
+  }
+}
+```
+<sub>*After you run `yarn build`, this webpack modification will have generated two directories within the `Public` directory: `css` & `fonts`*
+</sub>
+
+### Link Bundled CSS Files in index.html
+##### In index.html (`create-react-app/my-app/public/index.html`)
+Add the following lines:
+```html
+  <link rel="stylesheet" type="text/css" href="%PUBLIC_URL%/css/momentum-ui.min.css">
+  <link rel="stylesheet" type="text/css" href="%PUBLIC_URL%/css/momentum-ui-icons.min.css">
+```
+<sub>*This `%PUBLIC_URL%` references the public directory that now contains all required static assets (fonts, icons).*</sub> <br>
+<sub><https://create-react-app.dev/docs/using-the-public-folder/></sub>
+
+### Add a Web Components to your Project
+##### In App.js (`create-react-app/my-app/src/App.js`)
+1. Add the following import:
+```js
+  import '@momentum-ui/web-components';
+```
+OR import each individual web component
+```js
+  import '@momentum-ui/web-components/dist/comp/md-button';
+  import '@momentum-ui/web-components/dist/comp/md-icon';
+```
+<sub>*NOTE: You only need to import the web-components module at the top level of your application in order to use web components anywhere throughout.*
+</sub>
+
+2. Insert the following sample web component for testing purposes:
+```html
+<md-theme>
+  <md-button variant="green"><md-icon slot="icon" name="play_16"></md-icon><span slot="text">Code On!</span></md-button>
+</md-theme>
+```
+<sub>*NOTE: You must wrap your application with the `<md-theme>` element. It provides a set of core style resets and CSS custom variables that provide Theme color tokens, among other things. You can test these by toggling attributes `lumos` and/or `darkTheme` on the `<md-theme>` element.*
+</sub>
+
+##### Now it is time to get your app running locally! <br>
+(within `create-react-app/my-app` directory)
+
+1. `yarn` installs all dependencies.
+2. `yarn build` copies the required static assets for fonts and icons.
+3. `yarn start` launches project locally.
+
+ps: `yarn test` runs all tests files that have this file name structure: `<file>.test.ts` <br>
+<sub>*Feel free to run that and ensure that runs successfully with the existing sample test.*<sub>
+
+And you should see:
+
+![Screen Shot 2021-02-19 at 10 55 55 AM](https://user-images.githubusercontent.com/17099707/108549087-8c0e9880-72a1-11eb-9c71-7d6c6162f9cb.png)

package/VERSIONING.md

@@ -0,0 +1,28 @@
+# Momentum Web Components Maintenance Manual
+
+Please follow these guidelines to help decide appropriate  scenarios for publishing a new verison.
+
+### xx.xx.Patch Release when
+* 1 or more bug fixes are merged
+
+### xx.Minor.xx Release when
+* A new Component is added
+* A feature is added to existing components
+* Documentation is added
+* Optimization is added
+
+### Major.xx.xx Release when
+* Breaking, non-backwards compatible changes made
+
+### xx.xx.xx-dev.x Release when
+* Needing sustained testing of new features without `yarn link`
+* When dependant projects need bug or feature updates ahead of normal release timeline
+
+## To publish a new release
+1. Merge changes that share the same version semantic (i.e. two bug fix PRs)
+2. Increment the related version numeral from within the momentum-ui/web-components dir (best practice use `npm version [patch|minor|major]` unless making a `dev` release, then you can directly edit the package.json `version` property.)
+3. Run `npm login` to ensure you are connected to NPMjs. NOTE: you must be logged in to your NPMjs account that has the rights of a maintainer on @momentum-ui packages in order for it to publish. Do not use you Cisco credentials. 
+4. If not already authorized, run `yarn npm:auth` (This will allow publish internally on Artifactory as well as on npmjs)
+5. `yarn npm:publish` (This command will publish on Artifactory as well as on npmjs)
+
+If a combination of semantic scenarios are ready for merge at the same time, merge and release all Patch change PRs first, then Minor change PRs.

package/WEB_COMPONENTS_CRASH_COURSE.md

@@ -0,0 +1,255 @@
+# Web Components University
+
+So you want to contribute to Momentum-UI Web Components? Join the club! Web Components are quickly becoming one of the strongest standards of the modern web, and with the help of savvy developers such as yourself Momentum-UI has the potential to be a first class UI kit that makes the most of this next-generation technology.
+
+Web Components is a somewhat broad topic and I encourage first-timers to read [this great primer](https://css-tricks.com/an-introduction-to-web-components/) on the basics of web components from CSS Tricks. This introduction to the basic concepts and vanilla JavaScript application lays a good foundation to better uderstand and appreciate the Momentum approach that leverages LitElement, TypeScript, and some of our home-grown standards to make for a better Dev Experience and create complex functionality.
+
+#### [READ: CSS Tricks Intro to Web Components](https://css-tricks.com/an-introduction-to-web-components/)
+
+_**Note:** don't fret a deep understanding of the `<template>` and `document.importNode` usage. Many of these basics are abstracted away by LitElement, and a high-level understanding of vanilla Web Components is good enough to appreciate how LitElement improves developer experience._
+
+<hr>
+
+## Main Concepts (the short version)
+#### 1. Extending the `HTMLElement` base class
+Yep, you are basically just building on top of the native `HTMLElement` class and adding your own additions, like attributes and properties, methods, lifecycle control, HTML templates and CSS styles. In our library, we extend the `LitElement` class that provides more abstraction layers, but climb just a few steps up the prototype inheritance chain and you'll find `HTMLElement` right there providing the backbone.
+#### 2. Registering a Custom Element
+Once you have set up your new class with customizations, you must tell the browser to register your new component as a new HTML custom element. As a rule of the road, this must have at least one hyphen in it so `<my-custom-element>` is **good** but `<myelement>` is **bad**.
+
+*To quote CSS Tricks:*
+
+>Essentially, a custom element consists of two pieces: a tag name and a class that extends the built-in HTMLElement class. The most basic version of our custom element would look like this:
+
+```javascript=
+class MyCustomElement extends HTMLElement {
+  connectedCallback() { // lifecycle that follows the class constructor()
+    this.innerHTML = `<h1>Hello, World!</h1>`;
+  }
+}
+
+customElements.define('my-custom-element', MyCustomElement);
+```
+#### 3. Shadow DOM
+Your new custom element can be configured with its own `shadowRoot`, establishing a protected bubble of DOM called the ShadowDOM. This means that there is a impermeable boundary protecting private methods and properties from the outer DOM scope, and likewise protects the main DOM from ShadowDOM contents, like CSS styles that might otherwise invade the global namespace and unintentionally break styles.
+
+---
+
+Those are the "Big Three" ideas, each with their own tooling and best practices, but LitElement helps limit boilerplate and best practices used in the Momentum-UI library.
+
+We will now go into more depth, using some examples to show handy aspects of LitElement, TypeScript, CSS Constructable Stylesheets, `part()` selectors, CSS Variables for theming, home-grown helper mixins, and more.
+<br>
+<br>
+
+## Momentum-UI Web Components in Depth
+
+1. TypeScript Decorators
+2. Lifecycle Methods
+3. ShadowDOM: Slotted Content
+4. ShadowDOM: `::part()` Selector
+5. ShadowDOM: CSS Variables / CSS Custom Properties
+6. Constructable Stylesheets
+7. Momentum-UI Mixins / Abstract Classes
+8. CustomEvents
+9. LitHTML, LitCSS
+
+### TypeScript Decorators
+LitELement with Typescript enables the use of decorators that abstract away much of the boilerplate operations that are necessary in vanilla web component development. Here are some common cases.
+
+
+#### `@property()`
+The`@property()` decorator helps you establish a new property on your new component class. The properties you set here will be accessible as attributes on the new custom element (for primitive values) , or via `.property` notation if rich data is expected.
+This decorator effectively takes care of all the getter and setter methods, and eliminates the need of a constructor (in most cases).
+Explore the TS intellisense to see more control `@property()` offers, like setting an attribute name, or ensuring values are reflected.
+
+##### Example
+`@property({ type: String, attribute: "alt-text" }) altText : string = "default"`
+
+#### `@internalProperty()`
+The `@internalProperty()` decorator serves a similar function, but does not expose an attribute interface for users. It could be accessed as an element property unless marked as `private`. Properties initialized with this decorator are good for a component's internal logic
+
+##### Example
+`@internalProperty() loadingState : boolean = false`
+
+**NOTE:** you _can_ declare ordinary properties right within the class without a decorator, however `@property()` and `@internalProperty()` are wired to LitElement's lifecycle functions, and make it easier to trigger re-renders when those properties are updated.
+
+#### `@query()`
+The `@query()` decorator is a convenient way to grab a reference to an element that is within your web component's shadow root.
+
+##### Example
+`@query('div.special-class') divRef : HTMLElement | undefined = undefined`
+
+<hr>
+
+### Lifecycle Methods
+Vanilla JavaScript provides some elemental lifecycle methods, and LitElement provides even further assistance to ensure fine control over a web component's update and render cycle. We will give brief explanations of the most common ones here, but [read the docs for more details about their calling order and sample cases.](https://lit-element.polymer-project.org/guide/lifecycle)
+
+**NOTE:** All lifecycle methods must call `super()` to function.
+```javascript=
+connectedCallback() {
+  super.connectedCallback()
+
+  console.log('connected')
+}
+```
+
+#### `constructor()`
+Although many of the constructor's main duties are taken care of by property setting decorators discussed above, there may sometimes be special cases when you need to execute logic before the component has parsed any attributes or properties passed into it.
+#### `connectedCallback()`
+This is invoked when a component is added to the document’s DOM. A n example use case is when you need to add event listeners when LitElement binding patterns won't do.
+#### `disconnectedCallback()`
+Invoked when a component is removed from the document’s DOM. A good time to remove event listeners, for example
+#### `render()`
+Renders the HTML template within the web component's shadow DOM. *This method is an exception to the 'must call `super()`' rule*
+#### `firstUpdated()`
+This is called after the element’s DOM has been updated the first time, immediately before `updated` is called.
+#### `updated()`
+Called when the element’s DOM has been updated and rendered. Implement to perform some task after an update.
+
+[Read this to see the exact execution order LitElement enforces for the lifecycle methods.](https://lit-element.polymer-project.org/guide/lifecycle#reference)
+
+<hr>
+
+### ShadowDOM: Slotted Content
+The ShadowDOM is by its basic nature closed off from the surrounding DOM, protecting its elements and namespaces and concealing the functionality, structure and styles within the custom element. But we need an easy way to handle child elements with sufficient control.
+
+Using `<slot></slot>` elements within a web component's template provides a placeholder for any elements that appear in the Light DOM as children of our custom element.
+
+#### Unnamed Slot Example
+Say I have a card type element that has a specific structure, adds an image, etc . . . but I want it to be composable, allowing a developer to just pass their text in as a child (as opposed to say a `text` attribute that passes a string into a pre-defined element).
+
+So let us assume the web component's HTML template is like this:
+```htmlembedded=
+<div class="wrapper">
+    <div class="upper-section">
+        <img src=${this.imgSrc}>
+    </div>
+    <div class="text-section">
+        <slot></slot>
+    </div>
+</div>
+```
+And then when we use it, we know that the `<p>` content will render in the `<slot>` left for it.
+```htmlembedded=
+<custom-card-element img-src="https://www.some-site.com/sample.jpg">
+    <p>A bit of important text</p>
+</custom-card-element>
+```
+
+#### Named Slot Example
+But what if we have many places where we expect content insertion via child element? Consider this version:
+```htmlembedded=
+<div class="wrapper">
+    <div class="upper-section">
+        <img src=${this.imgSrc}>
+    </div>
+    <div class="text-section">
+        <slot name="text"></slot>
+    </div>
+    <div class="card-footer">
+        <slot name="footer"></slot>
+    </div>
+</div>
+```
+With named slots, we add additional control as to where we can expect our children to render. Notice the connection of the slot's `name` attribute to the child element's `slot` attribute:
+```htmlembedded=
+<custom-card-element img-src="https://www.some-site.com/sample.jpg">
+    <p slot="text">A bit of important text</p>
+    <p slot="footer">
+        Copyright 2021 <a href="#">Learn More</a>
+    </p>
+</custom-card-element>
+```
+
+**NOTE:** The key aspect of this discussion is about *composability* for the developers using your web components. Child/parent relationships are an intuitive and efficient way to write HTML, and many web components should feel like native HTML elements, rather than complex or cryptic APIs. Child content is not required for a web component to work, and there may be use cases where passing an attribute value is a better approach. Choose whatever creates the most natural developer experience.
+
+See this in action in `md-floating-modal`
+
+### ShadowDOM: `::part()` Selector
+As mentioned before, the CSS within a web component's shadow DOM is protected from the outer namespace, and likewise will not pollute the surrounding DOM with its style declarations. This is very helpful for fine control of your component's display, but it also makes it hard to do style changes or overrides when the component is used in an application.
+
+Let's take our card component again:
+```htmlembedded=
+<div class="wrapper">
+    <div class="upper-section">
+        <img src=${this.imgSrc}>
+    </div>
+    <div class="text-section">
+        <slot></slot>
+    </div>
+</div>
+```
+. . . and in usage:
+```htmlembedded=
+<custom-card-element img-src="https://www.some-site.com/sample.jpg">
+    <p>A bit of important text</p>
+</custom-card-element>
+```
+When I use this component, I will get whatever styles come with it. But say I need to override the height of the text section to better fit my particular use. There are a handful of tricky ways to get try to access the component's shadowRoot and query `div.text-section`, but many are too verbose, or brittle, or un-reachable via the CSS we have on our application. `::part()` allows the most direct way to style elements that are in the shadow DOM.
+
+You have to first declare the part name within the web component's template, like this: (the part name can be anything, just be sure it makes sense ;)
+```htmlembedded=
+<div class="wrapper">
+    <div class="upper-section">
+        <img src=${this.imgSrc}>
+    </div>
+    <div class="text-section" part="text-section">
+        <slot></slot>
+    </div>
+</div>
+```
+Which allows my consuming application to style like so:
+```css=
+custom-card-element::part(text-section) {
+    height: 4rem;
+}
+```
+
+See examples of this in action in `md-avatar`, `md-combobox`, `md-accoridan`, `md-tabs`, or just do a find-all in your IDE for `part="` and see more.
+
+### ShadowDOM: CSS Variables / CSS Custom Properties
+`::part()` is excellent for targeted overrides, but what if I want to make broad style changes, like a change-able theme? There is one other way to communicate some CSS through the shadowDOM boundary: CSS Custom Properties, AKA CSS Variables.
+
+These are not styles per se, but with coordinating the variables used by our styles within the shadow DOM with the parent elements that set those variable values, we can successfully modify designs on the go.
+
+This is the principle that powers the `<md-theme>` component and allows easy switching of light and dark modes in a shadow DOM world.
+
+In a nutshell, the Momentum WC library executes token-generating scripting at build time that compiles down to a collection of different CSS Variable schemas, like `lmDark.scss` and `lmLight.scss`, for example. Each schema ultimately sets a style like this:
+
+```css=
+// LIGHT MODE SCHEMA from lmLight.scss
+:root,
+:host {
+  --md-primary-text-color: #121212;
+  --md-secondary-text-color: #545454;
+}
+```
+
+```css=
+// DARK MODE SCHEMA from lmDark.scss
+:root,
+:host {
+  --md-primary-text-color: #f7f7f7;
+  --md-secondary-text-color: #b2b2b2;
+}
+```
+NOTICE: The `--` is syntax that means "here is a custom CSS property I am declaring, this is available in any location within the `:root/:host` where declared". Notice that they are the same. This means that down in the shadow DOM of my web component I can say:
+```css=
+.main-div {
+    color: var(--md-primary-text-color);
+}
+```
+And I will receiver the hue that is currently set to that property in the higher scope!
+
+`<md-theme>` works by swapping out the CSS file that is loaded, changing the CSS custom property values that are declared, but keeping the property values unchanged.
+
+### Constructable Stylesheets
+**Brief:** By using Webpack to load the SMACSS based style system and LitElement's `static get styles()` method, Styles are added to the CSS Object Module only once and adopted for each component instance, saving the browser from repeating and styles in the resulting DOM and improving performance. Chrome and Edge fully supported, Firefox and Safari polyfilled.
+### Momentum-UI Mixins / Abstract Classes
+**Brief:** Utility components like `FocusTrap` are abstract classes that can be used as the extension basis of a new component. They can provide a set of methods and properties for common component scenarios, like Focus Trapping, De Duping, Roving Tab Index, and more.
+### CustomEvents
+**Brief:** Creating Custom Events in a LitElement component is easy, and can be a helpful tool for making complex components or micro front ends that need to have finer control of binding data up the DOM tree through ShadowDOM. Be aware of caveats in React when a custom event is expected to be publicly visible.
+### LitHTML, LitCSS
+**Brief:** LitElement makes full leverage of template strings to make writing HTML templates for shadow DOM rendering super simple and native. LitHTML is ideal for writing true native HTML with interpolation using `${someVariable}`. Likewise, litCSS provides the same specifically for native composed CSS.
+
+
+THIS IS A LIVING DOCUMENT . . . if you have any feedback, requests for further information, or corrections please feel free to create an Issue ticket, or send an email to kehyde@cisco.com

package/babel.config.js

@@ -0,0 +1,4 @@
+/* eslint-disable */
+module.exports = {
+  presets: [["@babel/preset-env", { targets: { node: "current" } }]]
+};