@momentum-ui/web-components 2.16.5 → 2.16.8

package/src/mixins/ResizeMixin.ts

@@ -0,0 +1,142 @@
+/**
+ * Copyright (c) Cisco Systems, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/** This mixin provides a performant mechanism by which component can monitor changes to its size.
+ * For performance purpose, resizeObserver instance is static mixin property, and its shared across
+ * all components that applied ResizeMixin. (The `observe` method, which adds element as a new target to the list of observed elements,
+ * can pass either one element or multiple, so this mixin can manage mutliple elements that need's to be observed).
+ * When observed element's size changed, mixin dispatch `resize` event to handle it outside component tree.
+ *
+ * Example:
+ * @customElements("custom-element")
+ * class CustomElement extends ResizeMixin(LitElement) {
+ *    protected handleResize(contentRect: DOMRect) { <---- You override this with corresponding name in component directly.
+        // super.handleResize && super.handleResize(event); <---- Check to see whether the superclass defines a method of the same name, and if so, invoke that method.
+        // Do your listener work here.
+      }
+ * }
+ */
+
+import { LitElement } from "lit-element";
+import { DedupeMixin, wasApplied } from "./DedupeMixin";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyConstructor<A = LitElement> = new (...input: any[]) => A;
+
+export abstract class ResizeClass extends LitElement {
+  protected handleResize?(contentRect: DOMRect): void;
+  protected unobserveAll?(): void;
+}
+
+type ResizeObserverBoxOptions = "border-box" | "content-box" | "device-pixel-content-box";
+
+export interface ResizeObserverOptions {
+  box?: ResizeObserverBoxOptions;
+}
+
+export declare class ResizeObserver {
+  constructor(callback: ResizeObserverCallback);
+  observe: (target: Element, options?: ResizeObserverOptions) => void;
+  unobserve: (target: Element) => void;
+  disconnect: () => void;
+}
+
+export type ResizeObserverCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
+
+export interface ResizeObserverEntry {
+  readonly target: Element;
+  readonly contentRect: DOMRectReadOnly;
+  readonly borderBoxSize: ResizeObserverSize[];
+  readonly contentBoxSize: ResizeObserverSize[];
+  readonly devicePixelContentBoxSize: ResizeObserverSize[];
+}
+
+interface ResizeObserverSize {
+  readonly inlineSize: number;
+  readonly blockSize: number;
+}
+
+export const ResizeMixin = <T extends AnyConstructor<ResizeClass>>(base: T): T & AnyConstructor<ResizeClass> => {
+  if (wasApplied(ResizeMixin, base)) {
+    return base as ReturnType<() => T & AnyConstructor<ResizeClass>>;
+  }
+  class Resize extends base {
+    protected static _resizeObserver?: ResizeObserver;
+    protected static _animationFrameID?: number;
+
+    private _initResizeObserver() {
+      const observer = Resize._resizeObserver;
+      if (observer == null) {
+        Resize._resizeObserver = new ResizeObserver((entries: ResizeObserverEntry[]) => {
+          Resize._animationFrameID = requestAnimationFrame(() => {
+            if (Array.isArray(entries) && entries.length) {
+              entries.forEach((entry) => {
+                const { target, contentRect } = entry;
+                (target as Resize).handleResize(contentRect as DOMRect);
+              });
+            }
+          });
+        });
+      }
+    }
+
+    protected handleResize(contentRect: DOMRect) {
+      if (super.handleResize) {
+        super.handleResize(contentRect);
+      }
+      this.dispatchEvent(
+        new CustomEvent("resize", {
+          detail: {
+            contentRect
+          },
+          bubbles: true,
+          composed: true
+        })
+      );
+    }
+
+    protected unobserveAll() {
+      if (super.unobserveAll) {
+        super.unobserveAll();
+      }
+      const observer = Resize._resizeObserver;
+      if (observer) {
+        observer.disconnect();
+      }
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+
+      this._initResizeObserver();
+      const observer = Resize._resizeObserver;
+
+      if (observer && this.isConnected) {
+        observer.observe(this);
+      }
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      const observer = Resize._resizeObserver;
+      const timerId = Resize._animationFrameID;
+
+      if (observer) {
+        observer.unobserve(this);
+      }
+
+      if (timerId) {
+        cancelAnimationFrame(timerId);
+      }
+    }
+  }
+
+  DedupeMixin(ResizeMixin, Resize);
+
+  return Resize;
+};

package/src/mixins/RovingTabIndexMixin.test.ts

@@ -0,0 +1,60 @@
+import { elementUpdated, fixture, fixtureCleanup, html } from "@open-wc/testing-helpers";
+import { customElement, LitElement } from "lit-element";
+import { RovingTabIndexInterface, RovingTabIndexMixin } from "./RovingTabIndexMixin";
+
+describe("RovingTabIndex Mixin", () => {
+  let el: CustomElement & RovingTabIndexInterface;
+
+  @customElement("custom-element")
+  class CustomElement extends RovingTabIndexMixin(RovingTabIndexMixin(LitElement)) {
+    render() {
+      return html`
+        <div class="wrapper">
+          <slot></slot>
+        </div>
+      `;
+    }
+  }
+
+  afterEach(fixtureCleanup);
+  beforeEach(async () => {
+    el = await fixture<CustomElement & RovingTabIndexInterface>(html`
+      <custom-element selected="2">
+        <div>
+          <span>One</span>
+        </div>
+        <div>
+          <span>Two</span>
+        </div>
+        <div disabled>
+          <span>Three</span>
+        </div>
+        <div>
+          <span>Four</span>
+        </div>
+      </custom-element>
+    `);
+  });
+
+  test("should applying to component", () => {
+    expect(el).toHaveProperty("selected", expect.any(Number));
+    expect(el).toHaveProperty("getAvailableSelectedIndex", expect.any(Function));
+  });
+
+  test("should not set tabindex if selected item is not correct", () => {
+    expect(el.slotted[0].tabIndex).toBe(-1);
+  });
+
+  test("should set tabindex to next available item", async () => {
+    el.selected = 1;
+    await elementUpdated(el);
+    expect(el.slotted[0].tabIndex).toBe(-1);
+    expect(el.slotted[1].tabIndex).toBe(0);
+  });
+
+  test("should prevent focus in rovingPreventFocus property is passed", async () => {
+    el.rovingPreventFocus = true;
+    await elementUpdated(el);
+    expect(document.activeElement).not.toEqual(el);
+  });
+});

package/src/mixins/RovingTabIndexMixin.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright (c) Cisco Systems, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**This mixin using roving tabindex strategy to manage focus in a composite UI component,
+ * the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1".
+ * Benefit of using roving tabindex to manage focus is that the user agent will scroll the newly focused element into view.
+ *
+ * @property({ type: Number, reflect: true }) selected <--- index of focusable activeElement
+ *
+ * Example:
+ *
+ * @customElements("custom-element")
+ * class CustomElement extends RovingTabIndexMixin(LitElement) {
+      //custom element class implementation
+ * }
+ *  */
+
+import { LitElement, property } from "lit-element";
+import { DedupeMixin, wasApplied } from "./DedupeMixin";
+import { SlotableClass, SlotableInterface, SlottedMixin } from "./SlottedMixin";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyConstructor<A = LitElement> = new (...args: any[]) => A;
+
+export abstract class RovingTabIndexClass extends LitElement {
+  protected getAvailableSelectedIndex?(index: number, increment?: number): number;
+}
+
+export interface RovingTabIndexInterface {
+  selected: number;
+  rovingPreventFocus: boolean;
+}
+
+export const RovingTabIndexMixin = <T extends AnyConstructor<SlotableClass & RovingTabIndexClass>>(
+  base: T
+): T & AnyConstructor<RovingTabIndexInterface & SlotableInterface & SlotableClass & RovingTabIndexClass> => {
+  if (wasApplied(RovingTabIndexMixin, base)) {
+    return base as ReturnType<
+      () => T & AnyConstructor<RovingTabIndexInterface & SlotableInterface & SlotableClass & RovingTabIndexClass>
+    >;
+  }
+
+  class RovingTabIndex extends SlottedMixin(base) {
+    private _selected = 0;
+    @property({ type: Boolean, reflect: true, attribute: "roving-prevent-focus" }) rovingPreventFocus = false;
+
+    /**
+     * @deprecated Use `selected-index` instead.
+     * The index of the currently selected element.
+     */
+    @property({ type: Number, reflect: true })
+    get selected() {
+      return this._selected;
+    }
+    set selected(index: number) {
+      this.updateSelectedIndex(index);
+    }
+
+    /**
+     * The index of the currently selected element.
+     */
+    @property({ type: Number, reflect: true, attribute: "selected-index" })
+    get selectedIndex() {
+      return this._selected;
+    }
+    set selectedIndex(index: number) {
+      this.updateSelectedIndex(index);
+    }
+
+    /**
+     * Updates the selected index and manages the tabIndex of the slotted elements.
+     *
+     * @param index - The new selected index.
+     */
+    private updateSelectedIndex(index: number) {
+      const oldIndex = this._selected;
+
+      if (this.slotted[oldIndex]) {
+        const oldSelected = this.slotted[this._selected];
+        oldSelected.tabIndex = -1;
+      }
+
+      if (this.slotted[index]) {
+        const newSelected = this.slotted[index];
+        newSelected.tabIndex = 0;
+        if (!this.rovingPreventFocus) {
+          newSelected.focus();
+        }
+      }
+      this._selected = index;
+      this.requestUpdate("selected", oldIndex);
+    }
+
+    private isFocusable(slottedItem: Element) {
+      return !slottedItem.hasAttribute("disabled") && !slottedItem.hasAttribute("hidden");
+    }
+
+    protected slottedChanged() {
+      if (super.slottedChanged) {
+        super.slottedChanged();
+      }
+      const newIndex = this.getAvailableSelectedIndex(this.selected, 1);
+
+      if (newIndex !== -1) {
+        this.selected = newIndex;
+      }
+    }
+
+    protected getAvailableSelectedIndex(index: number, increment = 1) {
+      const slottedLength = this.slotted.length;
+
+      for (let i = 0, j = index; i < slottedLength; i += 1, j += increment) {
+        if (j < 0) {
+          j = slottedLength - 1;
+        } else if (j >= slottedLength) {
+          j = 0;
+        }
+        const slotted = this.slotted[j];
+        if (this.isFocusable(slotted)) {
+          return j;
+        }
+      }
+      return -1;
+    }
+  }
+
+  DedupeMixin(RovingTabIndexMixin, RovingTabIndex);
+
+  return RovingTabIndex;
+};

package/src/mixins/SlottedMixin.test.ts

@@ -0,0 +1,68 @@
+import { elementUpdated, fixture, fixtureCleanup } from "@open-wc/testing-helpers";
+import { customElement, html, LitElement, query } from "lit-element";
+import { SlotableInterface, SlottedMixin } from "./SlottedMixin";
+
+describe("SLotted Mixin", () => {
+  let el: CustomElement & SlotableInterface;
+
+  @customElement("custom-element")
+  class CustomElement extends SlottedMixin(SlottedMixin(LitElement)) {
+    @query("slot") defaultSlot!: HTMLSlotElement;
+
+    get slotElement() {
+      return this.defaultSlot;
+    }
+
+    render() {
+      return html`
+        <div class="wrapper">
+          <slot></slot>
+        </div>
+      `;
+    }
+  }
+
+  afterEach(fixtureCleanup);
+  beforeEach(async () => {
+    el = await fixture<CustomElement & SlotableInterface>(html`
+      <custom-element>
+        <div>
+          <span>One</span>
+        </div>
+        <div>
+          <span>Two</span>
+        </div>
+      </custom-element>
+    `);
+  });
+
+  test("should applying to component", () => {
+    expect(el).toHaveProperty("slottedChanged", expect.any(Function));
+    expect(el).toHaveProperty("filterSlotted", expect.any(Function));
+  });
+
+  test("should set `slotted` to the array of child nodes", () => {
+    expect(el.slotted).toBeInstanceOf(Array);
+    expect(el.slotted.length).toBe(2);
+  });
+
+  test("should update `items` value when removing nodes", async () => {
+    el.removeChild(el.slotted[0]);
+    await elementUpdated(el);
+    expect(el.slotted.length).toBe(1);
+  });
+
+  test("should update `items` value when removing nodes", async () => {
+    const div = document.createElement("div");
+    el.appendChild(div);
+    await elementUpdated(el);
+    expect(el.slotted.length).toBe(3);
+  });
+
+  test("should disallow external `items` modifications", async () => {
+    el.slotted = [];
+    el.requestUpdate("slotted");
+    await elementUpdated(el);
+    expect(el.slotted.length).toBe(2);
+  });
+});

package/src/mixins/SlottedMixin.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) Cisco Systems, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/** This mixin help to manage slottable nodes (light DOM children) that become the contents of `<slot>` element.
+ * 
+ * @property({ type: Array, attribute: false }) slotted <--- when an element is inserted in a slot.
+ * 
+ * Example:
+ * 
+ * @customElements("custom-element")
+ * class CustomElement extends SlottedMixin(LitElement) {
+ *  @query('slot[name="custom"]') tabSlot?: HTMLSlotElement;
+ *  get slotElement() { <--- You need to override this getter in parent component class to return specific slot (default or named) from your component’s render root.
+      return this.tabSlot;
+    }
+    protected filterSlotted() { <--- You need to override this method in parent component class to return filtered elements from slotted. (See tab implementation for example)
+      return Array.from(this.children) as HTMLElement[]; <--- By default this method return all children of custom component render root.
+    }
+    protected slottedChanged() { <--- You can override this method to handle when the node(s) contained in slotElement change.
+
+    }
+    render() {
+      return html`
+        <slot name="custom"></slot>
+      `;
+    }
+ * }
+ */
+
+import { LitElement, property, PropertyValues, query } from "lit-element";
+import { DedupeMixin, wasApplied } from "./DedupeMixin";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyConstructor<A = LitElement> = new (...args: any[]) => A;
+
+export interface SlotableInterface {
+  slotted: HTMLElement[];
+}
+
+export abstract class SlotableClass extends LitElement {
+  protected handleSlotted?(): void;
+  protected slottedChanged?(): void;
+  protected filterSlotted?(): HTMLElement[];
+}
+
+export const SlottedMixin = <T extends AnyConstructor<SlotableClass>>(
+  base: T
+): T & AnyConstructor<SlotableClass & SlotableInterface> => {
+  if (wasApplied(SlottedMixin, base)) {
+    return base as ReturnType<() => T & AnyConstructor<SlotableClass & SlotableInterface>>;
+  }
+
+  class Slotted extends base {
+    private _slotted: HTMLElement[] = [];
+    private _isSlotted = false;
+    @property({ type: Array, attribute: false })
+    get slotted() {
+      return this._slotted;
+    }
+    set slotted(value) {
+      if (this._isSlotted) {
+        const oldValue = this._slotted;
+        this._slotted = value;
+        this._isSlotted = false;
+        this.requestUpdate("slotted", oldValue);
+      }
+    }
+
+    @query("slot") _slotElement?: HTMLSlotElement;
+
+    get slotElement() {
+      return this._slotElement;
+    }
+
+    private handleSlotChange = () => {
+      this._isSlotted = true;
+      this.slotted = this.filterSlotted();
+    };
+
+    protected filterSlotted() {
+      return Array.from(this.children) as HTMLElement[];
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    protected slottedChanged() {}
+
+    protected firstUpdated(changedProperties: PropertyValues) {
+      super.firstUpdated(changedProperties);
+      if (this.slotElement) {
+        this.slotElement.addEventListener("slotchange", this.handleSlotChange);
+      }
+    }
+
+    protected update(changedProperties: PropertyValues) {
+      super.update(changedProperties);
+      if (changedProperties.has("slotted")) {
+        this.slottedChanged();
+      }
+    }
+
+    disconnectedCallback(): void {
+      if (this.slotElement) {
+        this.slotElement.removeEventListener("slotchange", this.handleSlotChange);
+      }
+    }
+  }
+
+  DedupeMixin(SlottedMixin, Slotted);
+
+  return Slotted;
+};

package/src/mixins/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Cisco Systems, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/* eslint-disable prettier/prettier */
+export { DedupeMixin } from "./DedupeMixin";
+export { FocusMixin } from "./FocusMixin";
+export { FocusTrapMixin } from "./FocusTrapMixin";
+export { ResizeMixin } from "./ResizeMixin";
+export { RovingTabIndexMixin } from "./RovingTabIndexMixin";
+export { SlottedMixin } from "./SlottedMixin";
+export { customElementWithCheck } from "./CustomElementCheck";
+

package/src/templates/color-table-data-string.hbs

@@ -0,0 +1,22 @@
+export const colorTableData = `
+{{#each this}}
+{{#with light}}
+--{{../prefix}}-{{../component}}, {{this}} _{{nodash this}}_, {{/with}}{{#with dark}}{{this}} _{{nodash this}}_
+{{/with}}
+{{#each this}}
+{{#with light}}
+--{{../../prefix}}-{{../../component}}-{{@key}}, {{this}} _{{nodash this}}_, {{/with}}{{#with dark}}{{this}} _{{nodash this}}_
+{{/with}}
+{{#each this}}
+{{#with light}}
+--{{../../../prefix}}-{{../../../component}}-{{@../key}}-{{@key}}, {{this}} _{{nodash this}}_, {{/with}}{{#with dark}}{{this}} _{{nodash this}}_
+{{/with}}
+{{#each this}}
+{{#with light}}
+--{{../../../../prefix}}-{{../../../../component}}-{{@../../key}}-{{@../key}}-{{@key}}, {{this}} _{{nodash this}}_, {{/with}}{{#with dark}}{{this}} _{{nodash this}}_
+{{/with}}
+{{/each}}
+{{/each}}
+{{/each}}
+{{/each}}
+`;

package/src/templates/colors-settings.hbs

@@ -0,0 +1,21 @@
+//------------------------------------------------------
+// Do not edit this file directly. These variables are
+// generated from the Momentum Design color tokens.
+// @momentum-ui/tokens/src/core/colors.js
+//------------------------------------------------------
+
+{{#each this}}
+{{#each this}}
+{{#if ../default}}
+{{#if @last}}
+$md-{{@../key}}: {{hex}} !default;
+{{else}}
+$md-{{@../key}}-{{@key}}: {{hex}} !default;
+{{/if}}
+{{else}}
+$md-{{@../key}}-{{@key}}: {{hex}} !default;
+{{/if}}
+{{/each}}
+
+{{/each}}
+

package/src/templates/colors.hbs

@@ -0,0 +1,35 @@
+//------------------------------------------------------
+// Do not edit this file directly. These variables are
+// generated from the Momentum Design color tokens.
+// @momentum-ui/tokens/src/core/colors.js
+//------------------------------------------------------
+
+{{#each this}}
+{{#each this}}
+{{#if ../default}}
+{{#if @last}}
+.md-color--{{@../key}} { color: {{hex}} !important; }
+{{else}}
+.md-color--{{@../key}}-{{@key}} { color: {{hex}} !important; }
+{{/if}}
+{{else}}
+.md-color--{{@../key}}-{{@key}} { color: {{hex}} !important; }
+{{/if}}
+{{/each}}
+
+{{/each}}
+
+{{#each this}}
+{{#each this}}
+{{#if ../default}}
+{{#if @last}}
+.md-background-color--{{@../key}} { background-color: {{hex}} !important; }
+{{else}}
+.md-background-color--{{@../key}}-{{@key}} { background-color: {{hex}} !important; }
+{{/if}}
+{{else}}
+.md-background-color--{{@../key}}-{{@key}} { background-color: {{hex}} !important; }
+{{/if}}
+{{/each}}
+
+{{/each}}

package/src/templates/component-colors.hbs

@@ -0,0 +1,40 @@
+//----------------------------------------------------------
+// Do not edit this file directly. This is generated from
+// Lumos color tokens & imported Momentum color tokens.
+// src/components/{{component}}/tokens/*.js
+// @momentum-ui/tokens/src/core/{{component}}.js
+//----------------------------------------------------------
+
+{{#each this}}
+{{#with light}}
+${{../../prefix}}-{{../../component}}-{{@key}}-light: {{this}} !default;
+{{/with}}
+{{#with dark}}
+${{../../prefix}}-{{../../component}}-{{@key}}-dark: {{this}} !default;
+{{/with}}
+{{#with common}}
+${{../../prefix}}-{{../../component}}-{{@key}}-common: {{this}} !default;
+{{/with}}
+{{#each this}}
+{{#with light}}
+${{../../../prefix}}-{{../../../component}}-{{@../key}}-{{@key}}-light: {{this}} !default;
+{{/with}}
+{{#with dark}}
+${{../../../prefix}}-{{../../../component}}-{{@../key}}-{{@key}}-dark: {{this}} !default;
+{{/with}}
+{{#with common}}
+${{../../../prefix}}-{{../../../component}}-{{@../key}}-{{@key}}-common: {{this}} !default;
+{{/with}}
+{{#each this}}
+{{#with light}}
+${{../../../../prefix}}-{{../../../../component}}-{{@../../key}}-{{@../key}}-{{@key}}-light: {{this}} !default;
+{{/with}}
+{{#with dark}}
+${{../../../../prefix}}-{{../../../../component}}-{{@../../key}}-{{@../key}}-{{@key}}-dark: {{this}} !default;
+{{/with}}
+{{#with common}}
+${{../../../../prefix}}-{{../../../../component}}-{{@../../key}}-{{@../key}}-{{@key}}-common: {{this}} !default;
+{{/with}}
+{{/each}}
+{{/each}}
+{{/each}}

package/src/templates/css-color-variables.hbs

@@ -0,0 +1,22 @@
+//------------------------------------------------------
+// Do not edit this file directly. These variables are
+// generated from the Momentum Design color tokens.
+// @momentum-ui/tokens/src/core/colors.js
+//------------------------------------------------------
+
+@mixin css-color-variables {
+{{#each this}}
+{{#each this}}
+{{#if ../default}}
+{{#if @last}}
+  --md-{{@../key}}: #{$md-{{@../key}} };
+{{else}}
+  --md-{{@../key}}-{{@key}}: #{$md-{{@../key}}-{{@key}} };
+{{/if}}
+{{else}}
+  --md-{{@../key}}-{{@key}}: #{$md-{{@../key}}-{{@key}} };
+{{/if}}
+{{/each}}
+
+{{/each}}
+}