@momentum-design/components 0.0.1

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

@@ -0,0 +1,70 @@
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-await-in-loop */
+import { Locator, Page, expect, TestInfo } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+import CONSTANTS from '../constants';
+
+interface Accessibility {
+  page: Page;
+  testInfo: TestInfo;
+}
+
+/**
+ * Contains common `accessibility` utils, which are useful when doing accessibility tests
+ */
+class Accessibility {
+  constructor(page: Page, testInfo: TestInfo) {
+    this.page = page;
+    this.testInfo = testInfo;
+  }
+
+  /**
+   * Attaches the provided scan results as JSON
+   * to the test report
+   * @param accessibilityScanResults
+   */
+  async attachA11yResults(accessibilityScanResults: any) {
+    await this.testInfo.attach('accessibility-scan-results', {
+      body: JSON.stringify(accessibilityScanResults, null, 2),
+      contentType: 'application/json',
+    });
+  }
+
+  /**
+   * Checks for Accessibility violations by scanning the whole
+   * page with axe-core, using the specific accessibility WCAG tags to check
+   * and disabled rules. The results will be attached as a JSON file
+   * to the test report afterwards.
+   *
+   * This function will fail if there are any accessibility violations.
+   */
+  async checkForA11yViolations() {
+    const accessibilityScanResults = await new AxeBuilder({ page: this.page })
+      .withTags(CONSTANTS.ACCESSIBILITY.WCAG_TAGS_TO_CHECK)
+      .disableRules(CONSTANTS.ACCESSIBILITY.RULES_TO_DISABLE)
+      .analyze();
+
+    await this.attachA11yResults(accessibilityScanResults);
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  }
+
+  /**
+   * pressAndCheckFocus utility function - it will press the provided `keyToPress` as often
+   * as the provided `elementsToBeFocused` are and checks afterwards, if the provided element of the
+   * `elementsToBeFocused` has been focused.
+   *
+   * If only 1 keyPress needs to be done, just simply provide the `elementsToBeFocused` array with
+   * 1 element, which should receive focus.
+   * @param keyToPress key which should be pressed
+   * @param elementsToBeFocused array of elements, which have to be focused after pressing a key
+   */
+  async pressAndCheckFocus(keyToPress: string, elementsToBeFocused: Array<Locator>) {
+    for (const elementToBeFocused of elementsToBeFocused) {
+      await this.page.keyboard.press(keyToPress);
+      await expect(elementToBeFocused).toBeFocused();
+    }
+  }
+}
+
+export default Accessibility;

package/config/playwright/setup/utils/visual-regression.ts

@@ -0,0 +1,35 @@
+import { Page, expect } from '@playwright/test';
+import type { ScreenShotOptions } from '../types';
+import CONSTANTS from '../constants';
+
+interface VisualRegression {
+  page: Page;
+}
+
+/**
+ * Contains common `visual-regression` utils, which are useful when doing visual-regression tests
+ */
+class VisualRegression {
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  /**
+   * Takes a screenshot of the whole page, with the passed in options
+   *
+   * @param name - name of the screenshot, file extension will be appended automatically!
+   * @param options - description
+   * @param options.element - element to take screenshot from
+   */
+  async takeScreenshot(name: string, options?: ScreenShotOptions): Promise<void> {
+    const elementToTakeScreenShotFrom = options?.element || this.page;
+
+    expect(await elementToTakeScreenShotFrom.screenshot(options)).toMatchSnapshot({
+      name: `${name}.${CONSTANTS.VISUAL_REGRESSION.FILE_EXTENSION}`,
+      threshold: CONSTANTS.VISUAL_REGRESSION.THRESHOLD,
+      maxDiffPixelRatio: CONSTANTS.VISUAL_REGRESSION.MAX_DIFF_PIXELS_RATIO,
+    });
+  }
+}
+
+export default VisualRegression;

package/config/plop/actions/AddComponent.ts

@@ -0,0 +1,21 @@
+import { join } from 'path';
+import { ActionType } from 'plop';
+import { folders, ACTION, TYPE, componentName, componentNamePrefix, componentNameSeparator } from '../constants';
+
+const base = `${join(`${folders.templates}`, `${ACTION.ADD}`, `${TYPE.COMPONENT}`)}`;
+
+export const AddComponent: ActionType = {
+  type: 'addMany',
+  base,
+  templateFiles: `${join(`${base}`, '**')}`,
+  destination: `${join(`${folders.components}`, `{{${componentName}}}`)}`,
+  data: {
+    componentName,
+    prefix: componentNamePrefix,
+    separator: componentNameSeparator,
+  },
+  globOptions: {
+    // allow hidden files to be copied as well:
+    dot: false,
+  },
+};

package/config/plop/actions/AddToComponentExports.ts

@@ -0,0 +1,16 @@
+/* eslint-disable max-len */
+import { join } from 'path';
+import { ActionType } from 'plop';
+import { folders, componentName, componentNamePrefix } from '../constants';
+
+export const AddToComponentExports: ActionType = {
+  type: 'modify',
+  path: `${join(`${folders.src}`, 'index.ts')}`,
+  pattern: /(};)/g,
+  data: {
+    componentName,
+    prefix: componentNamePrefix,
+  },
+  template:
+    `  {{sentenceCase prefix}}{{sentenceCase ${componentName}}},\n$1`,
+};

package/config/plop/actions/AddToComponentImports.ts

@@ -0,0 +1,16 @@
+/* eslint-disable max-len */
+import { join } from 'path';
+import { ActionType } from 'plop';
+import { folders, componentName, componentNamePrefix } from '../constants';
+
+export const AddToComponentImports: ActionType = {
+  type: 'modify',
+  path: `${join(`${folders.src}`, 'index.ts')}`,
+  pattern: /(\nexport)/g,
+  data: {
+    componentName,
+    prefix: componentNamePrefix,
+  },
+  template:
+    `import {{sentenceCase prefix}}{{sentenceCase ${componentName}}} from './components/{{${componentName}}}';\n$1`,
+};

package/config/plop/constants/index.ts

@@ -0,0 +1,31 @@
+import { join } from 'path';
+import CONSTANTS from '../../../src/utils/tag-name/constants';
+
+export enum PROMPT_TYPE {
+  INPUT = 'input',
+}
+
+export enum GENERATOR_NAME {
+  COMPONENT_GENERATOR = 'component'
+}
+
+export enum ACTION {
+  ADD = 'add',
+}
+
+export enum TYPE {
+  COMPONENT = 'component',
+}
+
+export const componentName: string = 'componentName';
+export const componentNamePrefix: string = CONSTANTS.NAMESPACE.PREFIX;
+export const componentNameSeparator: string = CONSTANTS.NAMESPACE.SEPARATOR;
+
+export const root: string = process.cwd();
+export const plop: string = `${join(root, 'config', 'plop')}`;
+
+export const folders = {
+  src: `${join(root, 'src')}`,
+  components: `${join(root, 'src', 'components')}`,
+  templates: `${join(plop, 'templates')}`,
+};

package/config/plop/esbuild.config.plop.js

@@ -0,0 +1,4 @@
+// TODO: look into how to use this from momentum-design inside of here without relative import
+const { plop } = require('../../../../../config/esbuild/esbuild.config.js');
+
+plop();

package/config/plop/generators/component/index.ts

@@ -0,0 +1,25 @@
+/* eslint-disable quotes */
+import { PlopGeneratorConfig } from 'plop';
+
+import { GENERATOR_NAME, componentName, PROMPT_TYPE } from '../../constants';
+import { AddComponent } from '../../actions/AddComponent';
+import { prompt } from '../../prompts';
+import { AddToComponentImports } from '../../actions/AddToComponentImports';
+import { AddToComponentExports } from '../../actions/AddToComponentExports';
+
+const componentNameMessage = `Choose the name of the component.
+Requirements
+- lowercase
+- without prefix e.g. "button"
+- no additional "hyphens", like "theme-provider"
+`;
+const generator: Partial<PlopGeneratorConfig> = {
+  description: 'Scaffold a new package',
+  prompts: [prompt(`${componentName}`, componentNameMessage, PROMPT_TYPE.INPUT)],
+  actions: [AddComponent, AddToComponentImports, AddToComponentExports],
+};
+
+export const ComponentGenerator = {
+  name: GENERATOR_NAME.COMPONENT_GENERATOR,
+  generator,
+};

package/config/plop/plopfile.ts

@@ -0,0 +1,6 @@
+import { NodePlopAPI } from 'plop';
+import { ComponentGenerator } from './generators/component';
+
+export default (plop: NodePlopAPI) => {
+  plop.setGenerator(ComponentGenerator.name, ComponentGenerator.generator);
+};

package/config/plop/prompts/index.ts

@@ -0,0 +1,8 @@
+import { PromptQuestion } from 'node-plop';
+import { PROMPT_TYPE } from '../constants';
+
+export const prompt = (name: string, message: string, type: PROMPT_TYPE = PROMPT_TYPE.INPUT): PromptQuestion => ({
+  type,
+  name,
+  message,
+});

package/config/plop/templates/add/component/index.ts.hbs

@@ -0,0 +1,12 @@
+import {{sentenceCase componentName}} from './{{componentName}}.component';
+import { TAG_NAME } from './{{componentName}}.constants';
+
+{{sentenceCase componentName}}.register(TAG_NAME);
+
+declare global {
+    interface HTMLElementTagNameMap {
+        ['{{prefix}}{{separator}}{{componentName}}']: {{sentenceCase componentName}}
+    }
+}
+
+export default {{sentenceCase componentName}};

package/config/plop/templates/add/component/{{componentName}}.component.ts.hbs

@@ -0,0 +1,22 @@
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import styles from './{{componentName}}.styles';
+import { Component } from '../../models';
+
+/**
+ * @slot - This is a default/unnamed slot
+ *
+ * @summary This is MyElement
+ *
+ * @tag {{prefix}}-{{componentName}}
+ * @tagname {{prefix}}-{{componentName}}
+ */
+class {{sentenceCase prefix}}{{sentenceCase componentName}} extends Component {
+  public override render() {
+    return html`<p>This is a dummy component!</p><slot></slot>`;
+  }
+
+  public static override styles = styles;
+}
+
+export default {{sentenceCase componentName}};

package/config/plop/templates/add/component/{{componentName}}.constants.ts.hbs

@@ -0,0 +1,5 @@
+import utils from '../../utils/tag-name';
+
+const TAG_NAME = utils.constructTagName('{{componentName}}');
+
+export { TAG_NAME };

package/config/plop/templates/add/component/{{componentName}}.e2e-test.ts.hbs

@@ -0,0 +1,67 @@
+import { test } from '../../../config/playwright/setup';
+import steps from '../../../config/playwright/setup/steps/accessibility';
+
+test.beforeEach(async ({ componentsPage }) => {
+  await componentsPage.mount({
+    html: `
+        <{{prefix}}{{separator}}{{componentName}} />
+      `,
+  });
+});
+
+test('{{prefix}}{{separator}}{{componentName}}', async ({ componentsPage }) => {
+  const {{componentName}} = componentsPage.page.locator('{{prefix}}-{{componentName}}');
+
+  // initial check for the {{componentName}} be visible on the screen:
+  await {{componentName}}.waitFor();
+
+  /**
+   * ACCESSIBILITY
+   */
+  await test.step('accessibility', async () => {
+    await steps.automaticA11yCheckStep(componentsPage);
+  });
+
+  /**
+   * VISUAL REGRESSION
+   */
+  await test.step('visual-regression', async () => {
+    await test.step('matches screenshot of element', async () => {
+      await componentsPage.visualRegression.takeScreenshot('{{prefix}}{{separator}}{{componentName}}', { element: {{componentName}} });
+    });
+  });
+
+  /**
+   * ATTRIBUTES
+   */
+  await test.step('attributes', async () => {
+    await test.step('attribute X should be present on component by default', async () => {
+      // TODO: add test here
+    });
+  });
+
+  /**
+   * INTERACTIONS
+   */
+  await test.step('interactions', async () => {
+    await test.step('mouse/pointer', async () => {
+      await test.step('component should fire callback x when clicking on it', async () => {
+        // TODO: add test here
+      });
+    });
+
+    await test.step('focus', async () => {
+      await test.step('component should be focusable with tab', async () => {
+        // TODO: add test here
+      });
+
+      // add additional tests here, like tabbing through several parts of the component
+    });
+
+    await test.step('keyboard', async () => {
+      await test.step('component should fire callback x when pressing y', async () => {
+        // TODO: add test here
+      });
+    });
+  });
+});

package/config/plop/templates/add/component/{{componentName}}.fixtures.ts.hbs

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+
+type Args = {}
+
+const base = (args: Args) => html`
+    <{{prefix}}{{separator}}{{componentName}}></{{prefix}}{{separator}}{{componentName}}>
+`;
+
+const fixtures = {
+  base,
+};
+
+export default fixtures;

package/config/plop/templates/add/component/{{componentName}}.stories.ts.hbs

@@ -0,0 +1,18 @@
+import type { Meta, StoryObj, Args } from '@storybook/web-components';
+import '.';
+import fixtures from './{{componentName}}.fixtures';
+
+const render = (args: Args) => fixtures.base(args);
+
+const meta: Meta = {
+  tags: ['autodocs'],
+  component: '{{prefix}}{{separator}}{{componentName}}',
+  render,
+  argTypes: {},
+};
+
+export default meta;
+
+export const Primary: StoryObj = {
+  args: {},
+};

package/config/plop/templates/add/component/{{componentName}}.styles.ts.hbs

@@ -0,0 +1,8 @@
+import { css } from 'lit';
+
+const styles = css`
+  :host {
+  }
+`;
+
+export default styles;

package/config/plop/tsconfig.plop.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "module": "CommonJS",
+    "esModuleInterop": true,
+    "moduleResolution": "node"
+  },
+  "exclude": [
+    "./templates"
+  ]
+}

package/config/storybook/MomentumStorybookTheme.js

@@ -0,0 +1,41 @@
+import { create } from '@storybook/theming/create';
+
+export default create({
+  base: 'dark',
+
+  // Typography for Manager 
+  // (can't use Inter here without a lot of workarounds):
+  fontBase: 'Helvetica Neue, sans-serif',
+  fontCode: 'monospace',
+
+  brandTitle: 'Momentum Design',
+  brandUrl: 'https://momentum.design',
+  brandImage: '/momentum-logo.png',
+  brandTarget: '_self',
+
+  colorPrimary: '#64b4fa',
+  colorSecondary: '#64b4fa',
+
+  // UI
+  appBg: '#1a1a1a',
+  appContentBg: '#262626',
+  appBorderColor: '#ffffff4d',
+
+  // Text colors
+  textColor: '#FFFFF2',
+  textInverseColor: '#000002',
+
+  // Toolbar default and active colors
+  barTextColor: '#FFFFF2',
+  barSelectedColor: '#64b4fa',
+  barBg: '#262626',
+
+  // Form colors
+  inputBg: '#FFFFFF',
+  inputBorder: '#ffffffb3',
+  inputTextColor: '#000002',
+
+  // Buttons:
+  buttonBg: '#FFFFFF',
+  buttonBorder: '#ffffffb3',
+});

package/config/storybook/main.js

@@ -0,0 +1,21 @@
+const config = {
+  stories: ['../../src/**/*.stories.@(js|jsx|ts|tsx)', '../../src/stories/**/*.mdx'],
+  addons: [
+    '@storybook/addon-controls',
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    '@storybook/addon-a11y',
+  ],
+  framework: {
+    name: '@storybook/web-components-vite',
+    options: {},
+  },
+  core: {
+    disableTelemetry: true, // 👈 Disables telemetry
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  staticDirs: ['./public'],
+};
+export default config;

package/config/storybook/manager.js

@@ -0,0 +1,17 @@
+import { addons } from '@storybook/manager-api';
+import momentum from './MomentumStorybookTheme';
+
+addons.setConfig({
+  bottomPanelHeight: '500',
+  panelPosition: 'bottom',
+  sidebar: {
+    showRoots: true,
+  },
+  toolbar: {
+    zoom: { hidden: false },
+    eject: { hidden: false },
+    copy: { hidden: false },
+    fullscreen: { hidden: false },
+  },
+  theme: momentum,
+});

package/config/storybook/preview.js

@@ -0,0 +1,63 @@
+import '../../src/components/themeprovider';
+import '@momentum-design/tokens/dist/css/core/complete.css';
+import '@momentum-design/tokens/dist/css/theme/webex/dark-stable.css';
+import '@momentum-design/tokens/dist/css/theme/webex/light-stable.css';
+import '@momentum-design/fonts/dist/css/fonts.css';
+
+import { setCustomElementsManifest } from '@storybook/web-components';
+import customElements from '../../data/custom-elements.json';
+import { themes } from './themes';
+import { withThemeProvider } from './provider/themeProvider';
+import { withIconProvider } from './provider/iconProvider';
+
+setCustomElementsManifest(customElements);
+
+const preview = {
+  parameters: {
+    a11y: {
+      options: {
+        runOnly: {
+          type: 'tag',
+          values: ['best-practice', 'wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'],
+        },
+      },
+    },
+    backgrounds: {
+      disable: true,
+      grid: {
+        disable: true,
+      },
+    },
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: {
+      controls: { expanded: true },
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+    options: {
+      storySort: {
+        order: ['System', 'Components'],
+      },
+    },
+  },
+  decorators: [withThemeProvider, withIconProvider],
+  globalTypes: {
+    theme: {
+      description: 'Global theme for components',
+      defaultValue: themes[0].displayName,
+      toolbar: {
+        // The label to show for this toolbar item
+        title: 'Theme',
+        icon: 'globe',
+        // Array of plain string values or MenuItem shape (see below)
+        items: themes.map((theme) => theme.displayName),
+        // Change title based on selected value
+        dynamicTitle: true,
+      },
+    },
+  },
+};
+
+export default preview;

package/config/storybook/provider/iconProvider.js

@@ -0,0 +1,8 @@
+import { html } from 'lit';
+
+export const withIconProvider = (story) =>
+  html`<mdc-iconprovider
+        url="/icons/svg"
+      >
+        ${story()}
+      </mdc-iconprovider>`;

package/config/storybook/provider/themeProvider.js

@@ -0,0 +1,31 @@
+import { html } from 'lit';
+import { themes } from '../themes';
+import '../themes/themes.css';
+
+const clearStyles = (element) => {
+  // eslint-disable-next-line no-restricted-syntax
+  for (const theme of themes) {
+    element.classList.remove(theme.className);
+  }
+};
+
+const applyStyle = (element, className) => {
+  element.classList.add(className);
+};
+
+export const withThemeProvider = (story, context) => {
+  const currentTheme = context.globals.theme;
+  const themeObject = themes.find((theme) => theme.displayName === currentTheme);
+
+  const body = document.querySelector('body.sb-show-main');
+  clearStyles(body);
+  applyStyle(body, themeObject.className);
+
+  return html`<mdc-themeprovider
+      id="theme-provider"
+      theme="${themeObject.name}"
+      themes="mds-theme-stable-darkWebex mds-theme-stable-lightWebex"
+    >
+      ${story()}
+    </mdc-themeprovider>`;
+};

package/config/storybook/themes/index.js

@@ -0,0 +1,14 @@
+export const themes = [
+  {
+    name: 'mds-theme-stable-darkWebex',
+    displayName: 'darkWebex',
+    backgroundColor: '#000000',
+    className: 'dark',
+  },
+  {
+    name: 'mds-theme-stable-lightWebex',
+    displayName: 'lightWebex',
+    backgroundColor: '#ffffff',
+    className: 'light',
+  },
+];

package/config/storybook/themes/themes.css

@@ -0,0 +1,15 @@
+.dark {
+    background-color: #000000;
+    height: 100vh;
+    background-image: url('/background-graphic.png');
+    background-repeat: no-repeat;
+    background-position: top right;
+}
+
+.light {
+    background-color: #ffffff;
+    height: 100vh;
+    background-image: url('/background-graphic.png');
+    background-repeat: no-repeat;
+    background-position: top right;
+}