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

package/src/lib/layout/README.md

@@ -0,0 +1,154 @@
+# layout
+
+Using layout, elements can be arranged easily in a variety of sizes and spaces that suit vivid design.
+
+```js
+<script type='module'>
+    import '@vonage/vivid/layout';
+</script>
+```
+
+```html preview
+<vwc-layout>
+  <img src="https://picsum.photos/id/1015/300/200">
+  <img src="https://picsum.photos/id/1016/300/200">
+  <img src="https://picsum.photos/id/1018/300/200">
+  <img src="https://picsum.photos/id/1019/300/200">
+  <img src="https://picsum.photos/id/1055/300/200">
+  <img src="https://picsum.photos/id/1050/300/200">
+</vwc-layout>
+```
+
+## Auto-sizing
+
+Use the `auto-sizing` attribute to set the initial preferred auto-sizing.
+
+- Type: `'fit'` | `'fill'`
+- Default: `'fit'`
+
+### fit
+
+```html preview
+<vwc-layout auto-sizing="fit">
+  <div style="border: 1px solid">fit</div>
+  <div style="border: 1px solid">fit</div>
+</vwc-layout>
+```
+
+### fill
+
+```html preview
+<vwc-layout auto-sizing="fill">
+  <div style="border: 1px solid">fill</div>
+  <div style="border: 1px solid">fill</div>
+</vwc-layout>
+```
+
+## Gutters
+
+Use the `gutters` attribute to set the initial preferred margin.
+
+- Type: `'base-small'` | `'base'` | `'base-large'`
+- Default: `''`
+
+```html preview
+<vwc-layout>
+  <div style="border: 1px solid">default</div>
+  <div style="border: 1px solid">default</div>
+</vwc-layout>
+<vwc-layout gutters="base-small">
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+</vwc-layout>
+<vwc-layout gutters="base">
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+</vwc-layout>
+<vwc-layout gutters="base-large">
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+</vwc-layout>
+```
+
+## Column-spacing
+
+Use the `column-spacing` attribute to set the initial preferred spacing of a column.
+
+- Type: `'base-small'` | `'base'` | `'base-large'`
+- Default: `'base'`
+
+```html preview
+<vwc-layout column-spacing="base-small">
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+</vwc-layout>
+<vwc-layout column-spacing="base">
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+</vwc-layout>
+<vwc-layout column-spacing="base-large">
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+</vwc-layout>
+```
+
+## Column-basis
+
+Use the `column-basis` attribute to set the initial preferred measure of a column.
+
+- Type: `'base-small'` | `'base'` | `'base-large'`
+- Default: `'base'`
+
+### base-small
+
+```html preview
+<vwc-layout column-basis="base-small">
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+  <div style="border: 1px solid">base-small</div>
+</vwc-layout>
+```
+
+### base
+
+```html preview
+<vwc-layout column-basis="base">
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+  <div style="border: 1px solid">base</div>
+</vwc-layout>
+```
+
+### base-large
+
+```html preview
+<vwc-layout column-basis="base-large">
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+  <div style="border: 1px solid">base-large</div>
+</vwc-layout>
+```
+
+### block
+
+```html preview
+<vwc-layout column-basis="block">
+  <div style="border: 1px solid">block</div>
+  <div style="border: 1px solid">block</div>
+  <div style="border: 1px solid">block</div>
+  <div style="border: 1px solid">block</div>
+  <div style="border: 1px solid">block</div>
+</vwc-layout>
+```
+
+## CSS Custom Properties
+
+| Name                         | Description                                      | Usage                                              |
+| ---------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| --layout-grid-template-columns | controls the grid-template-columns of the layout | repeat(`auto-sizing`, minmax(`column-basis`, 1fr)) |

package/src/lib/layout/index.ts

@@ -0,0 +1,18 @@
+import type { FoundationElementDefinition } from '@microsoft/fast-foundation';
+import { designSystem } from '../../shared/design-system';
+import { Layout } from './layout';
+import styles from './layout.scss';
+import { layoutTemplate as template } from './layout.template';
+
+
+/**
+ * Represents a layout custom element.
+ * layout is...
+ */
+export const VIVIDLayout = Layout.compose<FoundationElementDefinition>({
+	baseName: 'layout',
+	template: template as any,
+	styles,
+});
+
+designSystem.register(VIVIDLayout());

package/src/lib/layout/layout.scss

@@ -0,0 +1,40 @@
+@use 'sass:map';
+
+@use 'partials/variables' as variables;
+@use 'partials/mixins' as mixins;
+@use 'partials/functions' as functions;
+
+.control {
+	display: grid;
+	grid-auto-rows: min-content;
+
+	@include mixins.measurement(map.keys(variables.$bases)...) using ($basis) {
+		#{functions.get-selector-with-default(".column-basis", $basis, 'base', map.keys(variables.$bases))} {
+			grid-template-columns: var(
+				#{variables.$layout-grid-template-columns},
+				repeat(
+					var(#{variables.$auto-sizing}),
+					minmax(map.get(variables.$bases, $basis), 1fr)
+				)
+			);
+		}
+	}
+
+	@include mixins.measurement(map.keys(variables.$spaces)...) using ($space) {
+		#{functions.get-selector-with-default(".column-spacing", $space, 'base', map.keys(variables.$spaces))} {
+			gap: map.get(variables.$spaces, $space);
+		}
+	}
+
+	@include mixins.measurement(map.keys(variables.$spaces)...) using ($space) {
+		&.gutters-#{$space} {
+			margin: map.get(variables.$spaces, $space);
+		}
+	}
+
+	@include mixins.measurement(map.keys(variables.$auto-sizes)...) using ($size) {
+		#{functions.get-selector-with-default(".auto-sizing", $size, fit, map.keys(variables.$auto-sizes))} {
+			#{variables.$auto-sizing}: map.get(variables.$auto-sizes, $size);
+		}
+	}
+}

package/src/lib/layout/layout.spec.ts

@@ -0,0 +1,73 @@
+import { elementUpdated, fixture, getControlElement } from '@vivid-nx/shared';
+import { Size } from '../enums';
+import { AUTO_SIZING, Layout } from './layout';
+import '.';
+
+const COMPONENT_TAG = 'vwc-layout';
+
+describe('vwc-layout', () => {
+	let element: Layout;
+
+	beforeEach(async () => {
+		element = await fixture(`<${COMPONENT_TAG}>
+									<div style="border: 1px solid">test</div>
+									<div style="border: 1px solid">test</div>
+								</${COMPONENT_TAG}>`) as Layout;
+	});
+
+	describe('basic', () => {
+		it('initializes as a vwc-layout', async () => {
+			expect(element).toBeInstanceOf(Layout);
+			expect(element.gutters).toBeUndefined();
+			expect(element.columnBasis).toBeUndefined();
+			expect(element.columnSpacing).toBeUndefined();
+			expect(element.autoSizing).toBeUndefined();
+		});
+	});
+
+	describe('gutters', () => {
+		it('should set correct internal gutters class', async () => {
+			const gutters = Size.BaseLarge;
+
+			expect(getControlElement(element).classList.toString()).toEqual('control');
+			element.gutters = gutters;
+			await elementUpdated(element);
+			expect(getControlElement(element).classList.toString()).toEqual(`control gutters-${gutters}`);
+		});
+	});
+
+
+	describe('column-basis', () => {
+		it('should set correct internal column-basis style', async () => {
+			const columnBasis = Size.BaseLarge;
+
+			expect(getControlElement(element).classList.toString()).toEqual('control');
+			element.columnBasis = columnBasis;
+			await elementUpdated(element);
+			expect(getControlElement(element).classList.toString()).toEqual(`control column-basis-${columnBasis}`);
+		});
+	});
+
+	describe('column-spacing', () => {
+		it('should set correct internal column-spacing style', async () => {
+			const columnSpacing = Size.BaseLarge;
+
+			expect(getControlElement(element).classList.toString()).toEqual('control');
+			element.columnSpacing = columnSpacing;
+			await elementUpdated(element);
+			expect(getControlElement(element).classList.toString()).toEqual(`control column-spacing-${columnSpacing}`);
+		});
+	});
+
+
+	describe('auto-sizing', () => {
+		it('should set correct internal auto-sizing style', async () => {
+			const autoSizing = AUTO_SIZING.Fill;
+
+			expect(getControlElement(element).classList.toString()).toEqual('control');
+			element.autoSizing = autoSizing;
+			await elementUpdated(element);
+			expect(getControlElement(element).classList.toString()).toEqual(`control auto-sizing-${autoSizing}`);
+		});
+	});
+});

package/src/lib/layout/layout.template.ts

@@ -0,0 +1,29 @@
+import { html } 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 { Layout } from './layout';
+
+const getClasses = ({
+	columnBasis, gutters, columnSpacing, autoSizing
+}: Layout) => classNames(
+	'control',
+	[`column-basis-${columnBasis}`, Boolean(columnBasis)],
+	[`gutters-${gutters}`, Boolean(gutters)],
+	[`column-spacing-${columnSpacing}`, Boolean(columnSpacing)],
+	[`auto-sizing-${autoSizing}`, Boolean(autoSizing)],
+);
+
+/**
+ * The template for the {@link @vonage/vivid#Layout} component.
+ *
+ * @returns {ViewTemplate<Layout>} A template capable of creating HTMLView instances or rendering directly to DOM.
+ * @public
+ */
+export const layoutTemplate: (
+	context: ElementDefinitionContext,
+	definition: FoundationElementDefinition
+) => ViewTemplate<Layout> = () => html`
+        <div class="${getClasses}">
+			<slot></slot>
+		</div>`;

package/src/lib/layout/layout.ts

@@ -0,0 +1,46 @@
+import { attr } from '@microsoft/fast-element';
+import { FoundationElement } from '@microsoft/fast-foundation';
+import type { Size } from '../enums.js';
+
+
+export enum AUTO_SIZING { Fit = 'fit', Fill = 'fill' }
+type Gutters = Extract<Size, Size.BaseSmall | Size.Base | Size.BaseLarge>;
+type ColumnSpacing = Extract<Size, Size.BaseSmall | Size.Base | Size.BaseLarge>;
+type ColumnBasis = Extract<Size, Size.BaseSmall | Size.Base | Size.BaseLarge> | 'block';
+
+/**
+ * Base class for layout
+ *
+ * @cssprop [--layout-grid-template-columns=repeat([the `auto-sizing` mapped value],
+ * minmax([the `column-basis` mapped value], 1fr))] - Controls the `grid-template-columns` of the layout.
+ * @public
+ */
+export class Layout extends FoundationElement {
+	/**
+	 * sets the initial preferred margin from predefined available options
+	 *
+	 * @public
+	 */
+	@attr gutters?: Gutters;
+
+	/**
+	 * sets the initial preferred measure of a column from predefined available options
+	 *
+	 * @public
+	 */
+	@attr({ attribute: 'column-basis' }) columnBasis?: ColumnBasis;
+
+	/**
+	 * sets the initial preferred spacing of a column from predefined available options
+	 *
+	 * @public
+	 */
+	@attr({ attribute: 'column-spacing' }) columnSpacing?: ColumnSpacing;
+
+	/**
+	 * sets the initial preferred auto-sizing from predefined available options
+	 *
+	 * @public
+	 */
+	@attr({ attribute: 'auto-sizing' }) autoSizing?: AUTO_SIZING;
+}

package/src/lib/layout/partials/_functions.scss

@@ -0,0 +1,15 @@
+@function get-default-selector($list, $prefix) {
+	$selector: '';
+	@each $item in $list {
+		$selector: $selector + ':not(#{$prefix}-#{$item})';
+	}
+	@return $selector;
+}
+
+@function get-selector-with-default($prefix, $key, $default-key, $all-keys) {
+	$selector: '&#{$prefix}-#{$key}';
+	@if $key == $default-key {
+		$selector: '&#{get-default-selector($all-keys, $prefix)}', $selector;
+	}
+	@return $selector;
+}

package/src/lib/layout/partials/_mixins.scss

@@ -0,0 +1,5 @@
+@mixin measurement($types...) {
+	@each $type in $types {
+		@content($type);
+	}
+}

package/src/lib/layout/partials/_variables.scss

@@ -0,0 +1,23 @@
+$auto-sizing: --_auto-sizing; // interior. not API
+$layout-grid-template-columns: --layout-grid-template-columns;
+
+/* #region SIZEs */
+$auto-sizes: (
+	fill: auto-fill,
+	fit: auto-fit,
+);
+
+/* #region BASES */
+$bases: (
+	base-small: 10rem,
+	base: 20rem,
+	base-large: 30rem,
+	block: 1fr
+);
+
+/* #region SPACES */
+$spaces: (
+	base-small: 16px,
+	base: 24px,
+	base-large: 32px,
+);

package/src/lib/layout/ui.test.ts

@@ -0,0 +1,32 @@
+import * as path from 'path';
+import { expect, test } from '@playwright/test'; 
+import type { Page } from '@playwright/test';
+import {
+	extractHTMLBlocksFromReadme,
+	loadComponents,
+	loadTemplate
+} from '../../visual-tests/visual-tests-utils.ts';
+
+const components = ['layout'];
+test('should show the component', async ({ page }: { page: Page }) => {
+	const template = extractHTMLBlocksFromReadme(path.join(new URL('.', import.meta.url).pathname, 'README.md'))
+		.reduce((htmlString: string, block: string) => `${htmlString} <div style="margin: 5px;">${block}</div>`, '');
+
+	await loadComponents({
+		page,
+		components,
+	});
+	await loadTemplate({
+		page,
+		template,
+	});
+
+	const testWrapper = await page.$('#wrapper');
+
+	await page.waitForLoadState('networkidle');
+
+	expect(await testWrapper?.screenshot())
+		.toMatchSnapshot(
+			'./snapshots/layout.png',
+		);
+});