@momentum-design/components 0.0.1

package/.eslintrc.js

@@ -0,0 +1,16 @@
+const config = require('../../../.eslintrc.js');
+
+module.exports = {
+  ...config,
+  extends: [
+    ...config.extends,
+    'plugin:lit/recommended',
+  ],
+  parserOptions: { project: './tsconfig.json' },
+  rules: {
+    ...config.rules,
+    '@typescript-eslint/no-floating-promises': 'error',
+    'no-redeclare': 'off',
+    'implicit-arrow-linebreak': 'off',
+  },
+};

package/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# @momentum-design/components - Contributing Guide
+
+## Contributing
+
+This component package was generated with a script, please report any issues.

package/README.md

@@ -0,0 +1,39 @@
+# @momentum-design/components
+
+[![license: mit](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)](https://github.com/momentum-design/momentum-design/blob/main/LICENSE)
+![State](https://img.shields.io/badge/State-Alpha-blue?style=flat-square)
+
+## Overview
+
+This package is Work In Progress - there is no guarantee for consistency, stability till properly released.
+There will be breaking changes coming up - it is not recommended to consume this package in this early stage.
+
+## Steps to run this package
+
+- Follow the steps mentioned in the [first time setup](https://github.com/momentum-design/momentum-design/blob/main/CONTRIBUTING.md#first-time-setup).
+- Build all dependencies to run components package
+    ```
+    yarn telemetry build
+    yarn token-builder build
+    yarn tokens build
+    yarn common build
+    yarn builder build
+    yarn fonts build
+    yarn icons build
+    ```
+- Run this to start storybook and develop components
+    ```
+    yarn components dev
+    ```
+
+## Contributing
+
+See [our contributing guide](./CONTRIBUTING.md)
+
+## Scripts
+
+See [our script documentation](./SCRIPTS.md)
+
+## Testing
+
+See [our testing documentation](./TESTING.md)

package/SCRIPTS.md

@@ -0,0 +1,15 @@
+# @momentum-design/components - Scripts Guide
+
+## Scripts
+
+### dev
+- Run the Components Development tool locally
+
+### build
+- Builds to ./dist for export - only `dist` folder is published to NPM
+
+### test
+- Executes all tests
+
+### analyze
+- Runs linting and typescript, as well as all other static analysis scripts

package/TESTING.md

@@ -0,0 +1,38 @@
+# Testing
+
+## Unit Testing
+
+## E2E Testing
+
+Testing of the mounted, built component in real browsers.
+E2E Testing is done with the help of [Playwright](https://playwright.dev/).
+
+### Scope
+
+* Testing visual consistency of a component
+* Does the component display correctly in x browser (consistency and responsiveness)?
+* Does the components functions work correctly in x browser?
+* Is the component accessible in x browser?
+* Are interactions with the component working as expected in x browser?
+
+### Browser List to test
+
+* Chrome
+* Firefox
+* Edge
+* Safari/webkit
+
+### Local development
+
+For the best local development experience, the following E2E setup testing is recommended:
+
+1. Open 2 terminals
+2. In the first terminal, run `yarn components test:e2e:setup`
+    * This will spin up the local dev environment with dev server
+    * Wait till a `Serving!` message appears
+3. In the second terminal, run `yarn components test:e2e`
+    * This allows to run all E2E tests
+    * To run a specific E2E test, run `yarn components test:e2e XXX.e2e-test.ts`
+    * To run the tests in `headed mode`, run `yarn components test:e2e -- --headed`
+
+You can keep the first terminal open, while running/developing E2E tests in the second terminal.

package/config/api-extractor.json

@@ -0,0 +1,33 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  /**
+   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+   * standard settings to be shared across multiple projects.
+   *
+   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+   * resolved using NodeJS require().
+   *
+   * SUPPORTED TOKENS: none
+   * DEFAULT VALUE: ""
+   */
+  "extends": "../../../../config/api-extractor/api-extractor-base.json",
+
+
+  /**
+   * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
+   * analyzes the symbols exported by this module.
+   *
+   * The file extension must be ".d.ts" and not ".ts".
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+   * prepend a folder token such as "<projectFolder>".
+   *
+   * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+   */
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts"
+}

package/config/custom-elements-manifest.config.js

@@ -0,0 +1,28 @@
+module.exports = {
+  /** Globs to analyze */
+  globs: ['src/components/**/*.component.ts'],
+  /** Globs to exclude */
+  exclude: [
+    '*.js',
+  ],
+  /** Directory to output CEM to */
+  outdir: 'data',
+  /** Run in dev mode, provides extra logging */
+  dev: false,
+  /** Run in watch mode, runs on file changes */
+  watch: true,
+  /** Include third party custom elements manifests */
+  dependencies: false,
+  /** Output CEM path to `package.json`, defaults to true */
+  packagejson: false,
+  /** Enable special handling for litelement */
+  litelement: true,
+  /** Enable special handling for catalyst */
+  catalyst: false,
+  /** Enable special handling for fast */
+  fast: false,
+  /** Enable special handling for stencil */
+  stencil: false,
+  /** Provide custom plugins */
+  plugins: [],
+};

package/config/esbuild/configs/browser.js

@@ -0,0 +1,21 @@
+const { join } = require('path');
+
+const projectPath = process.cwd();
+const outPath = join('dist', 'browser', 'index.js');
+
+// todo: define browser targets here:
+const browsers = ['chrome114', 'firefox114'];
+
+const buildConfig = {
+  bundle: true,
+  entryPoints: [`${join(projectPath, 'src', 'index.ts')}`],
+  minify: true,
+  sourcemap: true,
+  outfile: `${join(projectPath, outPath)}`,
+  target: browsers,
+};
+
+module.exports = {
+  config: buildConfig,
+  outPath,
+};

package/config/esbuild/configs/e2e.js

@@ -0,0 +1,10 @@
+const { join } = require('path');
+
+const projectPath = process.cwd();
+const publicPath = join(projectPath, 'config', 'playwright', 'public');
+const port = 4000;
+
+module.exports = {
+  publicPath,
+  port,
+};

package/config/esbuild/esbuild-e2e.config.js

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-floating-promises */
+const esbuild = require('esbuild');
+const chalk = require('chalk');
+const { join } = require('path');
+const { config, outPath } = require('./configs/browser');
+const { publicPath, port } = require('./configs/e2e');
+
+const iife = async () => {
+  const ctx = await esbuild.context({
+    ...config,
+    outfile: `${join(publicPath, outPath)}`,
+  });
+
+  await ctx.watch();
+  await ctx.serve({
+    servedir: publicPath,
+    port,
+  });
+  console.log(chalk.cyan('Serving at http://localhost:4000'));
+};
+
+iife();

package/config/esbuild/esbuild.config.js

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/no-floating-promises */
+const esbuild = require('esbuild');
+const { config } = require('./configs/browser');
+
+const iife = async () => {
+  await esbuild.build(config);
+};
+
+iife();

package/config/playwright/playwright.config.ts

@@ -0,0 +1,107 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+import { devices } from '@playwright/test';
+import { port } from '../esbuild/configs/e2e';
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// require('dotenv').config();
+
+const url = `http://localhost:${port}`;
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+const config: PlaywrightTestConfig = {
+  testDir: '../../src',
+  testMatch: /.*\.e2e-test\.ts/,
+  /* Maximum time one test can run for. */
+  timeout: 30 * 1000,
+  expect: {
+    /**
+     * Maximum time expect() should wait for the condition to be met.
+     * For example in `await expect(locator).toHaveText();`
+     */
+    timeout: 5000,
+  },
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
+    actionTimeout: 0,
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: url,
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'retain-on-failure',
+  },
+
+  snapshotPathTemplate: '{testDir}/{testFileDir}/__screenshots__/{arg}{ext}',
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'Google Chrome',
+      use: {
+        ...devices['Desktop Chrome'],
+        channel: 'chrome',
+      },
+    },
+    // {
+    //   name: 'firefox',
+    //   use: {
+    //     ...devices['Desktop Firefox'],
+    //   },
+    // },
+
+    // {
+    //   name: 'webkit',
+    //   use: {
+    //     ...devices['Desktop Safari'],
+    //   },
+    // },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: {
+    //     ...devices['Pixel 5'],
+    //   },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: {
+    //     ...devices['iPhone 12'],
+    //   },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: {
+    //     channel: 'msedge',
+    //   },
+    // },
+  ],
+
+  /* Folder for test artifacts such as screenshots, videos, traces, etc. */
+  outputDir: 'test-results/',
+
+  /* Run your local dev server before starting the tests */
+  webServer: {
+    command: 'yarn test:e2e:setup',
+    url,
+    timeout: 240 * 1000,
+    reuseExistingServer: true,
+  },
+};
+
+export default config;

package/config/playwright/public/index.css

@@ -0,0 +1,43 @@
+@font-face {
+    font-family: "Momentum";
+    src: url("/dist/fonts/Inter.var.woff2") format("woff2");
+}
+
+body {
+    position: fixed;
+    height: 100%;
+    width: 100%;
+    margin: 0;
+    padding: 0;
+}
+
+#root {
+    height: 100%;
+    width: 100%;
+    background: var(--mds-color-theme-background-solid-primary-normal);
+}
+
+.themeWrapper {
+    display: flex;
+    flex-direction: column;
+    width: calc(30%);
+    height: auto;
+    background: var(--mds-color-theme-background-solid-primary-normal);
+    color: var(--mds-color-theme-text-primary-normal);
+    padding: 10px;
+    border: 1px solid var(--mds-color-theme-text-primary-normal)
+}
+
+.themeWrapper+.themeWrapper {
+    margin-top: 10px;
+}
+
+.colorBox {
+    width: 100%;
+    height: 10px;
+    border-radius: 5px;
+}
+
+.colorBox+.colorBox {
+    margin-top: 10px;
+}

package/config/playwright/public/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Momentum Components Dev Page</title>
+    <script type="module" src="/dist/browser/index.js"></script>
+    <link rel="stylesheet" href="index.css">
+    <link rel="stylesheet" href="/dist/complete.css">
+    <link rel="stylesheet" href="/dist/dark-stable.css">
+    <link rel="stylesheet" href="/dist/light-stable.css">
+</head>
+
+<body>
+    <mdc-themeprovider theme="mds-theme-stable-darkWebex"
+        themes="mds-theme-stable-darkWebex mds-theme-stable-lightWebex">
+        <mdc-iconprovider url="/dist/icons/svg">
+            <div id="root">
+            </div>
+        </mdc-iconprovider>
+    </mdc-themeprovider>
+</body>
+
+</html>

package/config/playwright/setup/Components.page.ts

@@ -0,0 +1,163 @@
+/* eslint-disable no-redeclare */
+import { Page, expect, Locator, TestInfo } from '@playwright/test';
+import type { ThemeName } from '../../../src/components/themeprovider/themeprovider.types';
+import utils from '../../../src/components/themeprovider/themeprovider.utils';
+import Accessibility from './utils/accessibility';
+import VisualRegression from './utils/visual-regression';
+
+const componentsDevPageTitle = 'Momentum Components Dev Page';
+const htmlRootElementSelector = '#root';
+
+interface MountOptions {
+  html: string;
+  clearDocument?: boolean;
+}
+
+interface ComponentsPage {
+  accessibility: Accessibility;
+  visualRegression: VisualRegression;
+  page: Page;
+  testInfo: TestInfo
+}
+
+/**
+ * Components Page Object Model
+ *
+ * This object model includes basic functionalities like setup, teardown, mount, etc.
+ * used for Momentum components E2E testing
+ */
+class ComponentsPage {
+  constructor(page: Page, testInfo: TestInfo) {
+    this.page = page;
+    this.testInfo = testInfo;
+
+    // creates utility objects on components page and inject dependencies:
+    this.accessibility = new Accessibility(this.page, this.testInfo);
+    this.visualRegression = new VisualRegression(this.page);
+  }
+
+  /**
+   * Sets the theme on the global theme provider
+   * for e2e tests. This allows testing
+   * with specified themes.
+   * @param theme - themeName to be used for setting theme on themeprovider
+   */
+  async setGlobalTheme(theme: ThemeName) {
+    const themeClass = utils.getFullQualifiedTheme(theme);
+    await this.page.evaluate(
+      (args) => {
+        const themeProvider = window.document.querySelector('body mdc-themeprovider');
+        if (themeProvider) {
+          themeProvider.setAttribute('theme', args.themeClass);
+        }
+      },
+      { themeClass },
+    );
+  }
+
+  /**
+   * **Setup function**
+   *
+   * to run before the test to navigate correctly
+   */
+  async setup() {
+    await this.navigate();
+  }
+
+  /**
+   * **TearDown function**
+   *
+   * to run after the test
+   */
+  async tearDown() {
+    await this.page.close();
+  }
+
+  /**
+   * **Navigate function**
+   *
+   * Path urls are allowed
+   *
+   * If no url provided, it navigates to baseURL
+   *
+   * - Go to the provided url
+   * - Await till page has been loaded
+   */
+  async navigate(url?: string) {
+    await this.page.goto(url || '');
+    await expect(this.page).toHaveTitle(componentsDevPageTitle);
+  }
+
+  /**
+   * Mount a html string to the index.html which gets displayed
+   *
+   * @param options - a object with options, including the `html` string to mount
+   */
+  async mount({ html, clearDocument = false }: MountOptions) {
+    await this.page.evaluate(
+      (args) => {
+        function htmlToElement(htmlString: string): Element {
+          const template = document.createElement('template');
+          template.innerHTML = htmlString.trim();
+          return template.content.firstChild as Element;
+        }
+        const rootElement = window.document.querySelector(args.htmlRootElementSelector);
+        if (rootElement) {
+          // delete children of textContent before mounting the passed in html:
+          if (args.clearDocument) {
+            rootElement.textContent = '';
+          }
+          rootElement.appendChild(htmlToElement(args.html));
+        }
+      },
+      { html, htmlRootElementSelector, clearDocument },
+    );
+  }
+
+  /**
+   * Wait for the event `eventName` to be fired on a HTMLElement, queried by the passed in `locator`
+   * @param locator - Playwright locator
+   * @param eventName - eventName to wait for to be fired on queried HTMLElement
+   * @returns Promise, which resolves when event `eventName` gets fired
+   */
+  async waitForEvent(locator: Locator, eventName: string) {
+    return locator.evaluate(
+      (element: HTMLElement, args) => new Promise((resolve: (value?: unknown) => void) => {
+        element.addEventListener(args.eventName, () => {
+          resolve();
+        });
+      }),
+      { eventName },
+    );
+  }
+
+  /**
+   * Set a attribute on a HTMLElement, queried by the passed in `locator`
+   * @param locator - Playwright locator
+   * @param qualifiedName - qualifiedName of the attribute to be set
+   * @param value - value of the attribute to be set
+   */
+  async setAttribute(locator: Locator, qualifiedName: string, value: any) {
+    await locator.evaluate(
+      (element: HTMLElement, args) => {
+        element.setAttribute(args.qualifiedName, args.value);
+      },
+      { qualifiedName, value },
+    );
+  }
+
+  /**
+   * Remove a attribute of a HTMLElement, queried by the passed in `locator`
+   * @param locator - Playwright locator
+   * @param qualifiedName - qualifiedName of the attribute to be removed
+   */
+  async removeAttribute(locator: Locator, qualifiedName: string) {
+    await locator.evaluate(
+      (element: HTMLElement, args) => {
+        element.removeAttribute(args.qualifiedName);
+      },
+      { qualifiedName },
+    );
+  }
+}
+export default ComponentsPage;

package/config/playwright/setup/constants.ts

@@ -0,0 +1,27 @@
+/**
+ * Accessibility constants
+ *
+ * WCAG_TAGS_TO_CHECK which should be checked,
+ * see full list here (Axe-core Tags): https://www.deque.com/axe/core-documentation/api-documentation/#axe-core-tags
+ * Note: WCAG Tags are cummulative, such that when confirming WCAG 2.2 AA,
+ * the less strict tags have to be added as well, like wcag2a, wcag2aa, wcag21aa
+ *
+ * RULES_TO_DISABLE which should not be checked,
+ * see full list here: https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md
+ */
+const ACCESSIBILITY = {
+  WCAG_TAGS_TO_CHECK: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'],
+  RULES_TO_DISABLE: [],
+};
+
+const VISUAL_REGRESSION = {
+  THRESHOLD: 0,
+  MAX_DIFF_PIXELS_RATIO: 0.03,
+  FILE_EXTENSION: 'png',
+};
+
+const CONSTANTS = {
+  ACCESSIBILITY,
+  VISUAL_REGRESSION,
+};
+export default CONSTANTS;

package/config/playwright/setup/index.ts

@@ -0,0 +1,42 @@
+import { test as base } from '@playwright/test';
+import { THEME_NAMES } from '../../../src/components/themeprovider/themeprovider.constants';
+import type { ThemeName } from '../../../src/components/themeprovider/themeprovider.types';
+import ComponentsPage from './Components.page';
+
+type Options = {
+  /**
+   * Theme to choose
+   */
+  theme: ThemeName
+};
+
+type Fixtures = {
+  /**
+   * componentsPage fixture - to be used to group momentum e2e utils
+   */
+  componentsPage: ComponentsPage;
+};
+
+// Extend base test by providing our fixtures based on Page Object Models
+// This new "test" can be used in multiple test files, and each of them will get the fixtures.
+export const test = base.extend<Fixtures & Options>({
+  theme: [THEME_NAMES.DARK_WEBEX, { option: true }],
+
+  componentsPage: async ({ page, theme }, use, testInfo) => {
+    const componentsPage = new ComponentsPage(page, testInfo);
+
+    if (theme) {
+      await componentsPage.setGlobalTheme(theme);
+    }
+    // navigate to the baseURL at the beginning
+    await componentsPage.setup();
+
+    // Use the fixture value in the test:
+    await use(componentsPage);
+
+    // Clean up at the end of the test:
+    await componentsPage.tearDown();
+  },
+});
+
+export { ComponentsPage };

package/config/playwright/setup/steps/accessibility.ts

@@ -0,0 +1,9 @@
+import { ComponentsPage, test } from '..';
+
+const automaticA11yCheckStep = (componentsPage: ComponentsPage) => test.step('check for A11y violations', async () => {
+  await componentsPage.accessibility.checkForA11yViolations();
+});
+
+export default {
+  automaticA11yCheckStep,
+};

package/config/playwright/setup/types.ts

@@ -0,0 +1,5 @@
+import { Locator, PageScreenshotOptions } from '@playwright/test';
+
+export type ScreenShotOptions = PageScreenshotOptions & {
+  element?: Locator;
+};