@momentum-design/components 0.0.1

package/src/components/icon/icon.component.ts

@@ -0,0 +1,155 @@
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import styles from './icon.styles';
+import { Component } from '../../models';
+import providerUtils from '../../utils/provider';
+import IconProvider from '../iconprovider/iconprovider.component';
+import { dynamicSVGImport } from './icon.utils';
+import { DEFAULTS } from './icon.constants';
+
+/**
+ * Icon component, which has to be mounted inside of a `IconProvider`
+ * component.
+ *
+ * The `IconProvider` component defines where icons should be consumed from (`url`).
+ * This `Icon` component accepts the `name` attribute, which will be
+ * the file name of the icon to be loaded from the given `url`.
+ *
+ * Once fetched, the icon will be mounted. If fetching wasn't successful,
+ * nothing will be shown.
+ *
+ * The `scale` attribute allows scaling the icon based on the provided
+ * `length-unit` attribute (which will either come from the IconProvider or
+ * could be overridden per icon). For example:
+ * if `scale = 1` and `length-unit = 'em'`, the size of the icon will be
+ * `width: 1em; height: 1em`.
+ *
+ * For accessibility the `role` and `aria-label` of the icon can be set.
+ *
+ * @tag mdc-icon
+ * @tagname mdc-icon
+ */
+class Icon extends Component {
+  @state()
+  private iconData?: HTMLElement;
+
+  @state()
+  private lengthUnitFromContext?: string;
+
+  /**
+   * Name of the icon (= filename)
+   */
+  @property({ type: String, reflect: true })
+  name?: string = DEFAULTS.NAME;
+
+  /**
+   * Scale of the icon (works in combination with length unit)
+   */
+  @property({ type: Number })
+  scale?: number = DEFAULTS.SCALE;
+
+  /**
+   * Length unit attribute for overridding length-unit from `IconProvider`
+   */
+  @property({ type: String, attribute: 'length-unit' })
+  lengthUnit?: string;
+
+  /**
+   * Role attribute to be set for accessibility
+   */
+  @property({ type: String })
+  override role: string | null = null;
+
+  /**
+   * Aria-label attribute to be set for accessibility
+   */
+  @property({ type: String, attribute: 'aria-label' })
+  override ariaLabel: string | null = null;
+
+  private iconProviderContext = providerUtils.consume({ host: this, context: IconProvider.Context });
+
+  /**
+   * Get Icon Data function which will fetch the icon (currently only svg)
+   * and sets state and attributes once fetched successfully
+   */
+  private async getIconData() {
+    if (this.iconProviderContext.value) {
+      const { fileExtension, url } = this.iconProviderContext.value;
+      if (url && fileExtension && this.name) {
+        const iconHtml = await dynamicSVGImport(url, this.name, fileExtension);
+
+        // update iconData state once fetched:
+        this.iconData = iconHtml as HTMLElement;
+
+        // when icon got fetched, set role and aria-label:
+        this.setRoleOnIcon();
+        this.setAriaLabelOnIcon();
+      }
+    }
+  }
+
+  /**
+   * Updates the size by setting the width and height
+   */
+  private updateSize() {
+    if (this.scale && (this.lengthUnit || this.lengthUnitFromContext)) {
+      const value = `${this.scale}${this.lengthUnit || this.lengthUnitFromContext}`;
+      this.style.width = value;
+      this.style.height = value;
+    }
+  }
+
+  private setRoleOnIcon() {
+    if (this.role) {
+      // pass through role attribute to svg if set on mdc-icon
+      this.iconData?.setAttribute('role', this.role);
+    } else {
+      this.iconData?.removeAttribute('role');
+    }
+  }
+
+  private setAriaLabelOnIcon() {
+    if (this.ariaLabel) {
+      // pass through aria-label attribute to svg if set on mdc-icon
+      this.iconData?.setAttribute('aria-label', this.ariaLabel);
+    } else {
+      this.iconData?.removeAttribute('aria-label');
+    }
+  }
+
+  override updated(changedProperties: Map<string, any>) {
+    super.updated(changedProperties);
+
+    if (changedProperties.has('name')) {
+      // fetch icon data if name changes:
+      this.getIconData().catch((err) => {
+        console.error(err);
+      });
+    }
+
+    if (changedProperties.has('role')) {
+      this.setRoleOnIcon();
+    }
+
+    if (changedProperties.has('ariaLabel')) {
+      this.setAriaLabelOnIcon();
+    }
+
+    if (changedProperties.has('scale') || changedProperties.has('lengthUnit')) {
+      this.updateSize();
+    }
+
+    if (this.lengthUnitFromContext !== this.iconProviderContext.value?.lengthUnit) {
+      this.lengthUnitFromContext = this.iconProviderContext.value?.lengthUnit;
+      this.updateSize();
+    }
+  }
+
+  override render() {
+    return html` ${this.iconData} `;
+  }
+
+  static override styles = styles;
+}
+
+export default Icon;

package/src/components/icon/icon.constants.ts

@@ -0,0 +1,10 @@
+import utils from '../../utils/tag-name';
+
+const TAG_NAME = utils.constructTagName('icon');
+
+const DEFAULTS = {
+  NAME: undefined,
+  SCALE: 1,
+};
+
+export { TAG_NAME, DEFAULTS };

package/src/components/icon/icon.e2e-test.ts

@@ -0,0 +1,101 @@
+import { expect } from '@playwright/test';
+import { ComponentsPage, test } from '../../../config/playwright/setup';
+import steps from '../../../config/playwright/setup/steps/accessibility';
+
+type SetupOptions = {
+  componentsPage: ComponentsPage;
+  name: string;
+  scale?: number;
+  role?: string;
+  ariaLabel?: string;
+};
+const setup = async (args: SetupOptions) => {
+  const { componentsPage, ...restArgs } = args;
+  await componentsPage.mount({
+    html: `
+    <mdc-icon 
+      name="${restArgs.name}" 
+      ${restArgs.scale ? `scale="${restArgs.scale}"` : ''}
+      ${restArgs.role ? `role="${restArgs.role}"` : ''}
+      ${restArgs.ariaLabel ? `aria-label="${restArgs.ariaLabel}"` : ''}
+    >
+    </mdc-icon>
+      `,
+    clearDocument: true,
+  });
+  const icon = componentsPage.page.locator('mdc-icon');
+  await icon.waitFor();
+  return icon;
+};
+
+test('mdc-icon', async ({ componentsPage }) => {
+  const name = 'accessibility-regular';
+  await setup({ componentsPage, name });
+
+  /**
+   * ACCESSIBILITY
+   */
+  await test.step('accessibility with default props', async () => {
+    await steps.automaticA11yCheckStep(componentsPage);
+  });
+
+  const iconWithRole = await setup({
+    componentsPage,
+    name,
+    role: 'graphics-document',
+    ariaLabel: 'test aria label',
+  });
+
+  await test.step('accessibility with role / aria-label passed in', async () => {
+    await steps.automaticA11yCheckStep(componentsPage);
+  });
+
+  /**
+   * VISUAL REGRESSION
+   */
+
+  // TODO: fix visual regression test on CI
+  // await test.step('visual-regression', async () => {
+  //   await test.step('matches screenshot of element with role / aria-label passed in', async () => {
+  //     await componentsPage.visualRegression.takeScreenshot('mdc-icon-default', { element: iconWithRole });
+  //   });
+
+  //   await test.step('matches screenshot of element with scale set to 2', async () => {
+  //     const iconScaled = await setup({
+  //       componentsPage,
+  //       name,
+  //       scale: 2,
+  //     });
+  //     await componentsPage.visualRegression.takeScreenshot('mdc-icon-scale', { element: iconScaled });
+  //   });
+  // });
+
+  /**
+   * ATTRIBUTES
+   */
+  await test.step('attributes', async () => {
+    await test.step('attributes should be present on component by default', async () => {
+      const icon = await setup({ componentsPage, name });
+      await expect(icon).toHaveAttribute('name', name);
+      await expect(icon).toHaveAttribute('style', 'width: 1em; height: 1em;');
+    });
+
+    await test.step('attributes should be present on component with scale passed in', async () => {
+      const icon = await setup({ componentsPage, name, scale: 2 });
+      await expect(icon).toHaveAttribute('name', name);
+      await expect(icon).toHaveAttribute('scale', '2');
+      await expect(icon).toHaveAttribute('style', 'width: 2em; height: 2em;');
+    });
+
+    await test.step('attributes should be present on component with role / aria-label passed in', async () => {
+      const iconWithRole = await setup({
+        componentsPage,
+        name,
+        role: 'graphics-document',
+        ariaLabel: 'test aria label',
+      });
+      await expect(iconWithRole).toHaveAttribute('name', name);
+      await expect(iconWithRole).toHaveAttribute('style', 'width: 1em; height: 1em;');
+    });
+  });
+});

package/src/components/icon/icon.stories.ts

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj, Args } from '@storybook/web-components';
+import '.';
+import { html } from 'lit';
+
+const render = (args: Args) => html` <mdc-icon name="${args.name}" scale="${args.scale}"></mdc-icon> `;
+const renderAccessibility = (args: Args) => html`
+  <mdc-icon name="${args.name}" scale="${args.scale}" role="${args.role}" aria-label="${args['aria-label']}"></mdc-icon>
+`;
+
+const meta: Meta = {
+  tags: ['autodocs'],
+  component: 'mdc-icon',
+  render,
+  argTypes: {},
+};
+
+export default meta;
+
+export const Primary: StoryObj = {
+  args: {
+    name: 'accessibility-regular',
+    scale: 1,
+  },
+};
+
+export const Accessibility: StoryObj = {
+  render: renderAccessibility,
+  args: {
+    name: 'accessibility-regular',
+    scale: 1,
+    role: 'graphics-document',
+    'aria-label': 'This is the accessibility icon',
+  },
+};

package/src/components/icon/icon.styles.ts

@@ -0,0 +1,15 @@
+import { css } from 'lit';
+import { hostFitContentStyles } from '../../utils/styles';
+
+const styles = [
+  hostFitContentStyles,
+  css`
+    svg {
+      height: 100%;
+      width: 100%;
+      fill: currentColor;
+    }
+  `,
+];
+
+export default styles;

package/src/components/icon/icon.utils.ts

@@ -0,0 +1,13 @@
+/* eslint-disable implicit-arrow-linebreak */
+
+const dynamicSVGImport = async (url: string, name: string, fileExtension: string): Promise<Element> =>
+  fetch(`${url}/${name}.${fileExtension}`)
+    .then((response) => {
+      if (!response.ok) {
+        throw new Error('There was a problem while fetching the icon!');
+      }
+      return response.text();
+    })
+    .then((iconResponse) => new DOMParser().parseFromString(iconResponse, 'text/html').body.children[0]);
+
+export { dynamicSVGImport };

package/src/components/icon/index.ts

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

package/src/components/iconprovider/iconprovider.component.ts

@@ -0,0 +1,76 @@
+import { property } from 'lit/decorators.js';
+import { Provider } from '../../models';
+import IconProviderContext from './iconprovider.context';
+import { ALLOWED_FILE_EXTENSIONS, DEFAULTS } from './iconprovider.constants';
+
+/**
+ * IconProvider component, which allows to be consumed from sub components
+ * (see `providerUtils.consume` for how to consume)
+ *
+ * Bundling icons will be up to the consumer of this component, such
+ * that only a url has to be passed in from which the icons will be
+ * fetched.
+ *
+ * @tag mdc-iconprovider
+ * @tagname mdc-iconprovider
+ */
+class IconProvider extends Provider<IconProviderContext> {
+  constructor() {
+    // initialise the context by running the Provider constructor:
+    super({
+      context: IconProviderContext.context,
+      initialValue: new IconProviderContext(),
+    });
+  }
+
+  public static get Context() {
+    return IconProviderContext.context;
+  }
+
+  /**
+   * Url of where icons will be fetched from
+   */
+  @property({ type: String })
+  url?: string;
+
+  /**
+   * File extension of icons, default: 'svg'
+   */
+  @property({ type: String, attribute: 'file-extension', reflect: true })
+  fileExtension?: string = DEFAULTS.FILE_EXTENSION;
+
+  /**
+   * Length unit used for sizing of icons, default: 'em'
+   */
+  @property({ type: String, attribute: 'length-unit', reflect: true })
+  lengthUnit?: string = DEFAULTS.LENGTH_UNIT;
+
+  private updateValuesInContext() {
+    // only update fileExtension on context if its an allowed fileExtension
+    if (this.fileExtension && ALLOWED_FILE_EXTENSIONS.includes(this.fileExtension)) {
+      this.context.value.fileExtension = this.fileExtension;
+    }
+    this.context.value.url = this.url;
+    this.context.value.lengthUnit = this.lengthUnit;
+  }
+
+  protected updateContext(): void {
+    let shouldUpdateConsumers = false;
+
+    if (
+      this.context.value.fileExtension !== this.fileExtension
+      || this.context.value.url !== this.url
+      || this.context.value.lengthUnit !== this.lengthUnit
+    ) {
+      this.updateValuesInContext();
+
+      shouldUpdateConsumers = true;
+    }
+
+    if (shouldUpdateConsumers) {
+      this.context.updateObservers();
+    }
+  }
+}
+
+export default IconProvider;

package/src/components/iconprovider/iconprovider.constants.ts

@@ -0,0 +1,12 @@
+import utils from '../../utils/tag-name';
+
+const TAG_NAME = utils.constructTagName('iconprovider');
+
+const ALLOWED_FILE_EXTENSIONS = ['svg'];
+
+const DEFAULTS = {
+  FILE_EXTENSION: 'svg',
+  LENGTH_UNIT: 'em',
+};
+
+export { TAG_NAME, DEFAULTS, ALLOWED_FILE_EXTENSIONS };

package/src/components/iconprovider/iconprovider.context.ts

@@ -0,0 +1,16 @@
+import { createContext } from '@lit-labs/context';
+
+import { TAG_NAME } from './iconprovider.constants';
+
+class IconProviderContext {
+  public fileExtension?: string;
+
+  public url?: string;
+
+  public lengthUnit?: string;
+
+  // create typed lit context as part of the IconProviderContext
+  public static context = createContext<IconProviderContext>(TAG_NAME);
+}
+
+export default IconProviderContext;

package/src/components/iconprovider/iconprovider.e2e-test.ts

@@ -0,0 +1,65 @@
+import { expect } from '@playwright/test';
+import { ComponentsPage, test } from '../../../config/playwright/setup';
+import steps from '../../../config/playwright/setup/steps/accessibility';
+import { DEFAULTS } from './iconprovider.constants';
+
+type SetupOptions = {
+  componentsPage: ComponentsPage;
+  url: string;
+  fileExtension?: string;
+  lengthUnit?: string;
+};
+const setup = async (args: SetupOptions) => {
+  const { componentsPage, ...restArgs } = args;
+  await componentsPage.mount({
+    html: `
+    <mdc-iconprovider 
+      url="${restArgs.url}" 
+      id="local" 
+      ${restArgs.fileExtension ? `file-extension="${restArgs.fileExtension}"` : ''}
+      ${restArgs.lengthUnit ? `length-unit="${restArgs.lengthUnit}"` : ''}
+    >
+      <mdc-icon name="accessibility-regular" scale="2"></mdc-icon>
+    </mdc-iconprovider>
+      `,
+  });
+};
+
+test('mdc-iconprovider', async ({ componentsPage }) => {
+  const url = '/dist/icons/svg';
+  await setup({ componentsPage, url });
+  const iconprovider = componentsPage.page.locator('mdc-iconprovider#local');
+
+  // initial check for the iconprovider be visible on the screen:
+  await iconprovider.waitFor();
+
+  /**
+   * ACCESSIBILITY
+   */
+  await test.step('accessibility', async () => {
+    await steps.automaticA11yCheckStep(componentsPage);
+  });
+
+  /**
+   * VISUAL REGRESSION
+   */
+  // TODO: fix visual regression test on CI
+  // await test.step('visual-regression', async () => {
+  //   await test.step('matches screenshot of element with default values', async () => {
+  //     await componentsPage.visualRegression.takeScreenshot('mdc-iconprovider', {
+  //       element: iconprovider,
+  //     });
+  //   });
+  // });
+
+  /**
+   * ATTRIBUTES
+   */
+  await test.step('attributes', async () => {
+    await test.step('attribute X should be present on component by default', async () => {
+      await expect(iconprovider).toHaveAttribute('url', url);
+      await expect(iconprovider).toHaveAttribute('file-extension', DEFAULTS.FILE_EXTENSION);
+      await expect(iconprovider).toHaveAttribute('length-unit', DEFAULTS.LENGTH_UNIT);
+    });
+  });
+});

package/src/components/iconprovider/iconprovider.stories.ts

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj, Args } from '@storybook/web-components';
+import '.';
+import './iconprovider.stories.utils';
+import { html } from 'lit';
+
+const render = (args: Args) => html`
+  <mdc-iconprovider url="${args.url}" file-extension="${args.fileExtension}" length-unit="${args.lengthUnit}">
+    <mdc-subcomponent-icon></mdc-subcomponent-icon>
+  </mdc-iconprovider>
+`;
+
+const meta: Meta = {
+  tags: ['autodocs'],
+  component: 'mdc-iconprovider',
+  render,
+  argTypes: {},
+};
+
+export default meta;
+
+export const Primary: StoryObj = {
+  args: {
+    url: '/test',
+    fileExtension: 'svg',
+    lengthUnit: 'em',
+  },
+};

package/src/components/iconprovider/iconprovider.stories.utils.ts

@@ -0,0 +1,27 @@
+import { html } from 'lit';
+import { Component } from '../../models';
+import IconProvider from './iconprovider.component';
+import providerUtils from '../../utils/provider';
+
+// Subcomponent to be rendered in storybook, to showcase that the
+// theme can be consumed as a subcomponent
+class SubComponentIconProvider extends Component {
+  currentTheme?: string;
+
+  private iconProviderContext = providerUtils.consume({ host: this, context: IconProvider.Context });
+
+  override render() {
+    return html`
+      <p>URL: ${this.iconProviderContext.value?.url}</p>
+      <p>File Extension: ${this.iconProviderContext.value?.fileExtension}</p>
+      <p>Length Unit: ${this.iconProviderContext.value?.lengthUnit}</p>
+    `;
+  }
+}
+
+SubComponentIconProvider.register('mdc-subcomponent-icon');
+declare global {
+  interface HTMLElementTagNameMap {
+    ['mdc-subcomponent-icon']: SubComponentIconProvider;
+  }
+}

package/src/components/iconprovider/index.ts

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