@vonage/vivid 3.0.0-next.6 → 3.0.0-next.7

package/src/lib/popup/README.md

@@ -0,0 +1,261 @@
+# popup
+
+Popup are used to display a message or notification to the user and are displayed on top of all other web page elements.
+Popup's goal is to provide additional, helpful content. To trigger the Popup, it should be paired with an anchor (e.g., a button). 
+
+```js
+<script type='module'>
+    import '@vonage/vivid/popup';
+</script>
+```
+## Anchor
+
+Use the `anchor` attribute to reference the ID to element in the popup’s owner document.
+
+The popup is positioned absolutely to its anchor.  It is recommended to wrap it with a div element and set its position `relative`.
+
+- Type: `string`
+- Default: `''`
+
+```js
+<div class="wrapper" style="position:relative;">
+  <vwc-button id="anchor"></vwc-button>
+  <vwc-popup anchor="anchor"></vwc-popup>
+</div>
+```
+## Open
+Use the `open` attribute to indicate whether the popup is open.
+
+- Type: `boolean`
+- Default: `false`
+
+```html preview
+<style>
+  .content {
+    width: 200px;
+    padding: 1rem;
+	}
+  .wrapper{
+    width: 100%;
+    height: 120px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+</style>
+<div class="wrapper">
+  <vwc-button id="anchor1" appearance='outlined' label='Click on me!'></vwc-button>
+  <vwc-popup id="popup" anchor="anchor1" open>
+      <div class="content">
+        <vwc-text tight font-face="body-2">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</vwc-text>
+      </div>
+  </vwc-popup>
+</div>
+<script>
+  anchor1.addEventListener('click', toggleOpen);
+  function toggleOpen() {
+	  popup.open = !popup.open;
+  }
+</script>
+```
+
+## Dismissible
+
+Add the `dismissible` attribute to add a close button to the popup.
+
+- Type: `boolean`
+- Default: `false`
+
+```html preview
+<style>
+  .content {
+    width: 120px;
+    padding: 1rem;
+	}
+  .wrapper{ 
+    width: 100%;
+    height: 120px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+</style>
+<div class="wrapper">
+  <vwc-button id="anchor2" appearance='outlined' label='Click on me!'></vwc-button>
+  <vwc-popup id="popup" anchor="anchor2" open dismissible>
+      <div class="content">
+        <vwc-text tight font-face="body-2">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</vwc-text>
+      </div>
+  </vwc-popup>
+</div>
+<script>
+  anchor2.addEventListener('click', toggleOpen);
+  function toggleOpen() {
+	  popup.open = !popup.open;
+  }
+</script>
+```
+## Arrow
+Add the `arrow` attribute to add a small triangle to indicate the trigger element.
+
+- Type: `boolean`
+- Default: `false`
+
+```html preview
+<style>
+  .content {
+    width: 200px;
+    padding: 1rem;
+	}
+  .wrapper{
+    width: 100%;
+    height: 120px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+</style>
+<div class="wrapper">
+  <vwc-icon id="anchor3" type='info-line'></vwc-icon>
+  <vwc-popup anchor="anchor3" open arrow>
+      <div class="content">
+        <vwc-text tight font-face="body-2">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</vwc-text>
+      </div>
+  </vwc-popup>
+</div>
+```
+## Alternate
+Add the `alternate` attribute to set the color-scheme to dark or light (depending on current user's system settings).
+
+- Type: `boolean`
+- Default: `false`
+
+```html preview
+<style>
+  .content {
+    width: 200px;
+    padding: 1rem;
+	}
+  .wrapper{
+    width: 100%;
+    height: 120px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+</style>
+<div class="wrapper">
+  <vwc-icon id="anchor4" type='info-line'></vwc-icon>
+  <vwc-popup anchor="anchor4" open alternate>
+      <div class="content">
+        <vwc-text tight font-face="body-2">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</vwc-text>
+      </div>
+  </vwc-popup>
+</div>
+```
+## Corner
+
+Use the `corner` attribute to set the placement of the popup around the anchor.
+
+- Type: `'top'` | `'top-start'` | `'top-end'` | `'right'` | `'right-start'` | `'right-end'` | `'bottom'` | `'bottom-start'` | `'bottom-end'`| `'left'` | `'left-start'`| `'left-end'`
+- Default: `'left'`
+
+```html preview
+<style>
+  .contentWrapper{
+    width: 70px;
+    padding: 0.25rem;
+  }
+	.square {
+		height: 150px;
+		width: 300px;
+		background-color: var(--vvd-color-neutral-10);;
+	  }
+	.wrapper{
+		width: 100%;
+		height: 250px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	  }
+	</style>
+	<div class="wrapper">
+	<div id="anchor5" class="square"></div>
+	<vwc-popup id="popup" anchor="anchor5" open corner="right-end">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">right-end</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="right">
+    <div class="contentWrapper">
+		  <vwc-text tight font-face="body-2">right</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="right-start">
+    <div class="contentWrapper">
+		  <vwc-text tight font-face="body-2">right-start</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="left-end">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">left-end</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="left">
+    <div class="contentWrapper">
+		  <vwc-text tight font-face="body-2">left</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="left-start">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">left-start</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="top-end">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">top-end</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="top">
+    <div class="contentWrapper">
+		  <vwc-text tight font-face="body-2">top</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="top-start">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">top-start</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="bottom-end">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">bottom-end</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="bottom">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">bottom</vwc-text>
+    </div>
+	</vwc-popup>
+	<vwc-popup id="popup" anchor="anchor5" open corner="bottom-start">
+    <div class="contentWrapper">
+			<vwc-text tight font-face="body-2">bottom-start</vwc-text>
+    </div>
+	</vwc-popup>
+	</div>
+```
+## Caveat
+
+Document elements display precedence is formed by the imaginary z-axis [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context), commonly by order of which elements are rendered and special properties (e.g. _z-index_).
+Popup component is a low level element, unaware of its document context, but in most cases required to overlay on top of all elements.
+
+A common practice used in apps / frameworks to promote a popup component to top other elements z-axis, is to utilise a service that dynamically appends a popup component to the end of the body element, when called for.
+
+This helps ensure elements don't render over top a popup undesirebly.
+
+## Methods
+### updatePosition()
+
+- Type: function
+- Returns: void
+
+Updates popup's position.

package/src/lib/popup/index.ts

@@ -0,0 +1,21 @@
+import '../elevation';
+import '../button';
+
+import type { FoundationElementDefinition } from '@microsoft/fast-foundation';
+import { designSystem } from '../../shared/design-system';
+import { Popup } from './popup';
+import styles from './popup.scss';
+import { popupTemplate as template } from './popup.template';
+
+
+/**
+ * Represents a popup custom element.
+ * popup is...
+ */
+export const VIVIDPopup = Popup.compose<FoundationElementDefinition>({
+	baseName: 'popup',
+	template: template as any,
+	styles,
+});
+
+designSystem.register(VIVIDPopup());

package/src/lib/popup/popup.scss

@@ -0,0 +1,43 @@
+$popup-bg: --vvd-color-surface-4dp;
+
+.control {
+	width: min-content;
+	background-color: var(#{$popup-bg});
+	border-radius: inherit;
+	contain: layout;
+
+	&:not(.open) {
+		display: none;
+	}
+}
+
+.popup-wrapper {
+	position: fixed;
+	border-radius: 6px;
+}
+
+.popup-content {
+	display: grid;
+	color: var(--vvd-color-on-canvas);
+
+	.dismissible & {
+		align-content: start;
+		grid-template-columns: 1fr auto;
+	}
+}
+
+.arrow {
+	position: absolute;
+	z-index: -1;
+	width: 8px;
+	height: 8px;
+	background-color: var(#{$popup-bg});
+	transform: rotate(45deg);
+}
+
+.dismissible {
+	align-self: flex-start;
+	margin-block-start: 0.25rem;
+	margin-inline-end: 0.25rem;
+}
+

package/src/lib/popup/popup.spec.ts

@@ -0,0 +1,265 @@
+import {
+	ADD_TEMPLATE_TO_FIXTURE,
+	elementUpdated,
+	fixture,
+	getControlElement
+} from '@vivid-nx/shared';
+import * as floatingUI from '@floating-ui/dom';
+import type { Button } from '../button/button';
+import { Popup } from './popup';
+import '.';
+
+const COMPONENT_TAG = 'vwc-popup';
+
+describe('vwc-popup', () => {
+	/**
+	 *
+	 */
+	async function setupPopupToOpenWithAnchor() {
+		const anchor = await setAnchor();
+		element.anchor = 'anchor';
+		await elementUpdated(element);
+		element.open = true;
+		return anchor;
+	}
+
+	let element: Popup;
+
+	beforeEach(async () => {
+		element = await fixture(`<${COMPONENT_TAG}></${COMPONENT_TAG}>`) as Popup;
+		global.ResizeObserver = jest.fn()
+			.mockImplementation(() => ({
+				observe: jest.fn(),
+				unobserve: jest.fn(),
+				disconnect: jest.fn()
+			}));
+	});
+
+	afterEach(function () {
+		jest.clearAllMocks();
+	});
+
+	describe('clean observable', () => {
+		it('should clean observable on disconnectedCallback', async function () {
+			const cleanupMock = jest.fn();
+			jest.spyOn(floatingUI, 'autoUpdate').mockReturnValue(cleanupMock);
+			await setupPopupToOpenWithAnchor();
+			element.disconnectedCallback();
+			expect(cleanupMock).toHaveBeenCalled();
+		});
+
+		it('should clean observable when anchor is undefined', async function () {
+			const cleanupMock = jest.fn();
+			jest.spyOn(floatingUI, 'autoUpdate').mockReturnValue(cleanupMock);
+			await setupPopupToOpenWithAnchor();
+			element.anchor = '';
+			await elementUpdated(element);
+			expect(cleanupMock).toHaveBeenCalled();
+		});
+	});
+
+	describe('viewport visibility transition', function () {
+
+		const computePositionResult = {
+			'x': -15,
+			'y': 0,
+			'placement': 'left',
+			'strategy': 'fixed',
+			'middlewareData': {
+				'flip': {},
+				'hide': {
+					'referenceHiddenOffsets': {
+						'top': 0,
+						'right': 0,
+						'bottom': 0,
+						'left': 0
+					},
+					'referenceHidden': true
+				},
+				'inline': {},
+				'arrow': {
+					'y': 0,
+					'centerOffset': 0
+				},
+				'offset': {
+					'x': -12,
+					'y': 0
+				}
+			}
+		};
+
+		beforeEach(function () {
+			jest.spyOn(floatingUI, 'computePosition');
+		});
+
+		afterEach(function () {
+			(floatingUI.computePosition as jest.MockedFunction<any>).mockRestore();
+		});
+
+		/**
+		 * @param hidden
+		 */
+		async function makePopupHidden(hidden = true) {
+			computePositionResult.middlewareData.hide.referenceHidden = hidden;
+			(floatingUI.computePosition as jest.MockedFunction<any>).mockReturnValue(Promise.resolve(computePositionResult));
+			await element.updatePosition();
+		}
+
+		it('should be hidden when not in viewport', async function () {
+			await setupPopupToOpenWithAnchor();
+			await makePopupHidden(true);
+
+			expect(element.popupEl.style.visibility)
+				.toEqual('hidden');
+		});
+
+		it('should be hidden when not in viewport', async function () {
+			await setupPopupToOpenWithAnchor();
+			await makePopupHidden(false);
+			expect(element.popupEl.style.visibility)
+				.toEqual('visible');
+		});
+	});
+
+	describe('basic', () => {
+		it('initializes as a vwc-popup', async () => {
+			expect(element)
+				.toBeInstanceOf(Popup);
+			expect(element.open)
+				.toBeFalsy();
+			expect(element.arrow)
+				.toBeFalsy();
+			expect(element.dismissible)
+				.toBeFalsy();
+			expect(element.anchor)
+				.toBeUndefined();
+			expect(element.corner)
+				.toEqual('left');
+		});
+	});
+
+	describe('show', () => {
+		it('should set "open" to true', async () => {
+			await setAnchor();
+			element.anchor = 'anchor';
+			await elementUpdated(element);
+
+			element.open = true;
+			element.updatePosition();
+			await elementUpdated(element);
+
+			expect(element.open)
+				.toEqual(true);
+		});
+	});
+
+	describe('hide', () => {
+		it('should set "open" to false', async () => {
+			element.open = true;
+
+			element.open = false;
+			element.updatePosition();
+			await elementUpdated(element);
+
+			expect(element.open)
+				.toEqual(false);
+		});
+	});
+
+	describe('render arrow', () => {
+		it('should remove the arrow class on the container if arrow is false', async () => {
+			expect(element.shadowRoot?.querySelector('.arrow'))
+				.toBeNull();
+		});
+		it('should set the arrow class on the container if arrow is true', async () => {
+			element.arrow = true;
+			element.open = true;
+			await elementUpdated(element);
+
+			await setAnchor();
+			element.anchor = 'anchor';
+			await elementUpdated(element);
+
+			element.arrowEl = element.shadowRoot?.querySelector('.arrow') as HTMLElement;
+			element.updatePosition();
+			await elementUpdated(element);
+
+			expect(element.shadowRoot?.querySelector('.arrow'))
+				.not
+				.toBeNull();
+		});
+	});
+
+	describe('render dismiss', () => {
+		it('should remove the dismiss class on the container if dismissible is false', async () => {
+			expect(element.shadowRoot?.querySelector('.dismissible'))
+				.toBeNull();
+		});
+		it('should set the dismiss class on the container if dismissible is true', async () => {
+			element.dismissible = true;
+
+			await elementUpdated(element);
+			expect(element.shadowRoot?.querySelector('.dismissible'))
+				.not
+				.toBeNull();
+		});
+	});
+
+	describe('handle dismiss', () => {
+		it('should hide when dismiss button is clicked', async () => {
+			await setAnchor();
+			element.anchor = 'anchor';
+			element.dismissible = true;
+			await elementUpdated(element);
+
+			element.open = true;
+			expect(element.open)
+				.toEqual(true);
+
+			await elementUpdated(element);
+			const dismissButton = element.shadowRoot?.querySelector('vwc-button');
+			(dismissButton as HTMLElement).click();
+			await elementUpdated(element);
+
+			expect(element.open)
+				.toEqual(false);
+		});
+	});
+
+	describe('alternate', () => {
+		it('should set to alternate', async () => {
+			expect(getControlElement(element)
+				.getAttribute('part'))
+				.toEqual('');
+			element.alternate = true;
+
+			await elementUpdated(element);
+			expect(getControlElement(element)
+				.getAttribute('part'))
+				.toEqual('vvd-theme-alternate');
+		});
+	});
+
+	describe('accessibility', () => {
+		it('should set aria-hidden', async () => {
+			expect(getControlElement(element)
+				.getAttribute('aria-hidden'))
+				.toEqual('true');
+			element.open = true;
+
+			await elementUpdated(element);
+			expect(getControlElement(element)
+				.getAttribute('aria-hidden'))
+				.toEqual('false');
+		});
+	});
+
+	/**
+	 *
+	 */
+	async function setAnchor() {
+		const anchorEl = await fixture('<vwc-button id="anchor"></vwc-button>', ADD_TEMPLATE_TO_FIXTURE) as Button;
+		await elementUpdated(anchorEl);
+		return anchorEl;
+	}
+});

package/src/lib/popup/popup.template.ts

@@ -0,0 +1,41 @@
+import { html, ref, when } from '@microsoft/fast-element';
+import { classNames } from '@microsoft/fast-web-utilities';
+import type { ViewTemplate } from '@microsoft/fast-element';
+import type { ElementDefinitionContext, FoundationElementDefinition } from '@microsoft/fast-foundation';
+import type { Popup } from './popup';
+
+const getClasses = ({
+	open, dismissible, alternate
+}: Popup) => classNames(
+	'control',
+	['open', Boolean(open)],
+	['dismissible', Boolean(dismissible)],
+	['alternate', Boolean(alternate)]
+);
+
+/**
+ * The template for the {@link @vonage/vivid#Popup} component.
+ *
+ * @returns {ViewTemplate<Popup>} A template capable of creating HTMLView instances or rendering directly to DOM.
+ * @public
+ */
+export const popupTemplate: (
+	context: ElementDefinitionContext,
+	definition: FoundationElementDefinition
+) => ViewTemplate<Popup> = () => html`
+  <vwc-elevation>
+    <!--the popup-wrapper is needed for alternating the inside of the popup nd not its shadow-->
+	  <div class="popup-wrapper" ${ref('popupEl')}>
+			<div class="${getClasses}" aria-hidden="${(x) => x.open ? 'false' : 'true'}"
+				part="${(x) => x.alternate ? 'vvd-theme-alternate' : ''}">
+				<div class="popup-content">
+					<slot></slot>
+					${when(x => x.dismissible,
+		html<Popup>`<vwc-button size="base-small" @click="${x => (x.open = false)}"
+						class="dismissible" icon="close-small-solid" shape="pill"></vwc-button>`)}
+				</div>
+				${when(x => x.arrow,
+		html<Popup>`<div class="arrow" ${ref('arrowEl')}></div>`)}
+			</div>
+    </div>
+  </vwc-elevation>`;