feat(vwc-text): 1st draft to support font faces (#942)

* feat(vwc-text): 1st draft to support font faces

* text component 80%

* font face types autogenerated

* story

* supports font faces

* documentation

* story introduction

* adding ui-tests

* tests

* tests pass

* story correct path

* update text

* typo

* unrelated

* syntax

* irrelevant FONT_FACES_SUPPORTED

* temporary modification

* removed irrelevant files

* restored modification

* added doc visualizations

* typo

* add type ramp instead

* semantics

* typo

* update a11y test

Co-authored-by: tveinfeld <67224311+tveinfeld@users.noreply.github.com>
Co-authored-by: Yonatan Kra <yonatan.kra@vonage.com>

__snapshots__/vwc-text.md

@@ -0,0 +1,10 @@
+# `vwc-text`
+
+#### `should internal contents`
+
+```html
+<slot>
+</slot>
+
+```
+

common/design-tokens/package.json

@@ -27,6 +27,6 @@
  "@vonage/vvd-design-tokens-properties": "0.6.3",
  "lodash": "^4.17.21",
  "ramda": "^0.27.1",
- "style-dictionary": "^2.10.3"
+ "style-dictionary": "^3.0.1"
  }
 }

common/design-tokens/src/builders/typography/index.js

@@ -0,0 +1,2 @@
+export { render as renderTypographySassMixin } from './typography.sass-mixins.js';
+export { render as renderTypographyTypes } from './typography.types.js';

common/design-tokens/src/builders/typography/typography.types.js

@@ -0,0 +1,53 @@
+import { resolve } from 'path';
+
+import StyleDictionaryPackage from 'style-dictionary';
+import fs from 'fs';
+import _ from 'lodash';
+
+const propertiesPath = resolve('../../node_modules/@vonage/vvd-design-tokens-properties');
+
+
+StyleDictionaryPackage.registerFormat({
+ name: 'custom/format/enums',
+ formatter: _.template(
+ fs.readFileSync(resolve('templates/ts-enum.template'))
+ ),
+});
+
+// HAVE THE STYLE DICTIONARY CONFIG DYNAMICALLY GENERATED
+function getStyleDictionaryConfig() {
+ return {
+ source: [
+ `${propertiesPath}/globals/typography/*.json`,
+ `${propertiesPath}/typography/web.json`,
+ ],
+ platforms: {
+ ts: {
+ transformGroup: 'js',
+ buildPath: `${resolve()}/`,
+ files: [
+ {
+ destination: 'build/types/font-faces.ts',
+ format: 'custom/format/enums',
+ mapName: 'VVDFontFace',
+ filter: {
+ attributes: {
+ category: 'typography'
+ }
+ },
+ }
+ ]
+ }
+ }
+ };
+}
+
+
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export const render = () => {
+ console.log('\n🔁\x1b[2mProcessing typography types\x1b[0m');
+
+ StyleDictionaryPackage.extend(getStyleDictionaryConfig()).buildPlatform('ts');
+
+ console.log('\n\x1b[2m================================================================\x1b[0m');
+};

common/design-tokens/src/index.js

@@ -1,13 +1,14 @@
 import { render as schemesRender } from './builders/render-schemes.js';
 import { render as schemesCouplingRender } from './builders/render-schemes-coupling.js';
-import { render as typographyRender } from './builders/render-typography.js';
+import { renderTypographySassMixin, renderTypographyTypes } from './builders/typography/index.js';
 
 
 console.log('\n\x1b[32m=== Design tokens build started ====\x1b[0m');
 
 
 schemesRender();
 schemesCouplingRender();
-typographyRender();
+renderTypographySassMixin();
+renderTypographyTypes();
 
 console.log('\n\x1b[32m=== Design tokens build completed ====\n\x1b[0m');

common/design-tokens/templates/ts-enum.template

@@ -0,0 +1,42 @@
+<%
+ // for backward compatibility we need to have the user explicitly hide it
+ const showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true;
+ if(showFileHeader) {
+ let header = '';
+ header += "/*\n Do not edit directly";
+ header += "\n Generated on " + new Date().toUTCString();
+ header += "\n*/\n";
+ print(header);
+ print('\n');
+ }
+
+ const types = allProperties.map(({ attributes: { type } }) => type);
+
+ const typesSet = new Set(types);
+
+ print(`export enum ${this.mapName||'tokens'} {`);
+
+ function toKebab(str) {
+ return str.replace(/[_\s]+/g, '-')
+ }
+
+ function toTitle(str) {
+ return toKebab(str)
+ .split('-')
+ .map(word => {
+ return word.slice(0, 1).toUpperCase() + word.slice(1)
+ })
+ .join('')
+ }
+
+ var indent = ' ';
+
+ print(
+ Array.from(typesSet).map(type =>
+ `\n${indent}${toTitle(type)} = '${type}'`
+ )
+ );
+
+
+ print(`\n}`);
+%>

components/text/package.json

@@ -0,0 +1,41 @@
+{
+ "name": "@vonage/vwc-text",
+ "version": "2.13.0",
+ "description": "> TODO: description",
+ "author": "yinonov <yinon@hotmail.com>",
+ "homepage": "https://github.com/Vonage/vivid/tree/master/components/text#readme",
+ "license": "ISC",
+ "main": "vwc-text.js",
+ "module": "vwc-text.js",
+ "files": [
+ "src",
+ "*.js",
+ "*.ts",
+ "*.map"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/vonage/vivid.git",
+ "directory": "components/text"
+ },
+ "scripts": {
+ "test": "echo \"Error: run tests from root\" && exit 1",
+ "build:typescript": "tsc -b",
+ "build:styles": "umbrella-style-modules",
+ "build": "yarn run build:styles && yarn run build:typescript"
+ },
+ "bugs": {
+ "url": "https://github.com/Vonage/vivid/issues"
+ },
+ "dependencies": {
+ "@vonage/vvd-core": "2.13.0",
+ "lit-element": "^2.4.0",
+ "tslib": "^2.3.0"
+ },
+ "devDependencies": {
+ "@vonage/vvd-design-tokens": "2.13.0",
+ "@vonage/vvd-typography": "2.13.0",
+ "@vonage/vvd-umbrella": "2.13.0",
+ "typescript": "^4.3.2"
+ }
+}

components/text/readme.md

@@ -0,0 +1,52 @@
+# vwc-text
+
+Represents a text custom element.
+The component provisions the Vivid typography font faces and connotations supported by our design system.
+
+##### typography scale
+![typography font faces scale image](assets/images/type-ramp.jpeg)
+
+### Basic usage
+
+The following will generate a `headline-1` styled font face
+```html
+<vwc-text font-face="headline-1">
+ lorem ipsum dolor sit amet
+</vwc-text>
+```
+
+### Semantic usage
+
+HTML semantics indicates authoring intent and is important for accessibility, search engine optimizations and clear code.
+Therefore, you'd probably need to nest html tags that apply different styling and may affect the font face appearance provided by the `vwc-text` element.
+This component takes care of overriding the direct nested child within the component to `inherit` applied font face (if not over specified by the application styles).
+
+custom elements (not extending a built-in native element with the is="" attribute) have a [transparent content model](https://html.spec.whatwg.org/multipage/dom.html#transparent-content-models).
+This means they can be ignored when a parent is validating its own content model`s children.
+
+note that web component cannot style or access any descendent greater than a direct child.
+
+The following will generate a `caption` styled font face even though it's wrapped by a `h1` tag -
+```html
+<vwc-text font-face="caption">
+ <h1>
+ lorem ipsum dolor sit amet, consectetur adipiscing elit
+ </h1>
+</vwc-text>
+```
+
+On the other hand, 'vwc-text' can nest within semantic tags instead -
+
+```html
+<h1>
+ <vwc-text font-face="caption">
+ lorem ipsum dolor sit amet, consectetur adipiscing elit
+ </vwc-text>
+</h1>
+```
+
+## Properties
+
+| Property | Attribute | Type |
+| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fontFace` | `font-face` | `body-1` \| `body-1-bold` \| `body-1-code` \| `body-1-link` \| `body-2` \| `body-2-bold` \| `body-2-code` \| `body-2-link` \| `button` \| `button-dense` \| `button-enlarge` \| `caption` \| `caption-bold` \| `caption-code` \| `caption-link` \| `headline-1` \| `headline-2` \| `subtitle-1` \| `subtitle-2` \| `title-1` \| `title-2` |

components/text/src/vwc-text-base.ts

@@ -0,0 +1,15 @@
+import '@vonage/vvd-core';
+import { VVDFontFace } from '@vonage/vvd-design-tokens/build/types/font-faces';
+import {
+ html, LitElement, property, TemplateResult
+} from 'lit-element';
+
+
+export class VWCTextBase extends LitElement {
+ @property({ type: String, reflect: true, attribute: 'font-face' })
+ fontFace?: VVDFontFace;
+
+ protected render(): TemplateResult {
+ return html`<slot></slot>`;
+ }
+}

components/text/src/vwc-text.scss

@@ -0,0 +1,18 @@
+@use '@vonage/vvd-typography/scss/typography' as typography;
+@use '@vonage/vvd-design-tokens/build/scss/typography-variables/web' as typography-scale;
+
+
+:host {
+ @include typography.typography-cat-shorthand('body-1');
+ display: contents;
+}
+
+::slotted(*) {
+ font: inherit;
+}
+
+@each $key, $value in typography-scale.$typography-category-list {
+ :host([font-face="#{$key}"i]) {
+ @include typography.typography-cat-shorthand($key);
+ }
+}

components/text/src/vwc-text.ts

@@ -0,0 +1,17 @@
+import '@vonage/vvd-core';
+import { customElement } from 'lit-element';
+
+import { VWCTextBase } from './vwc-text-base.js';
+import { style } from './vwc-text.css.js';
+
+
+@customElement('vwc-text')
+export class VWCText extends VWCTextBase {
+ static styles = style;
+}
+
+declare global {
+ interface HTMLElementTagNameMap {
+ 'vwc-text': VWCText;
+ }
+}

components/text/stories/arg-types.js

@@ -0,0 +1,12 @@
+import { VVDFontFace } from '@vonage/vvd-design-tokens/build/types/font-faces';
+
+
+export const argTypes = {
+ 'font-face': {
+ control: {
+ type: 'select',
+ options: Object.values(VVDFontFace),
+ }
+ },
+ styles: { table: { disable: true } },
+};

components/text/stories/text-introduction.config.mjs

@@ -0,0 +1,23 @@
+import {
+ relocateStaticResources,
+} from '../../../.storybook/build-scripts/create-stories-from-md.mjs';
+
+export default {
+ sourcePath: '../readme.md',
+ outputName: 'text-introduction',
+ story: {
+ title: 'Alpha/Components/Text',
+ name: 'Introduction',
+ parameters: {
+ options: {
+ showPanel: false,
+ isToolshown: false
+ }
+ }
+ },
+ htmlPostProcess: (htmlText) => {
+ return relocateStaticResources(htmlText, [
+ 'assets/images/type-ramp.jpeg'
+ ], 'components/text');
+ },
+};

components/text/stories/text.stories.js

@@ -0,0 +1,18 @@
+import '@vonage/vwc-text/vwc-text.js';
+import { html } from 'lit-element';
+import { spread } from '@open-wc/lit-helpers';
+import { argTypes } from './arg-types.js';
+import { VVDFontFace } from '@vonage/vvd-design-tokens/build/types/font-faces';
+
+export default {
+ title: 'Alpha/Components/Text',
+ component: 'vwc-text',
+ argTypes
+};
+
+const Template = args => html`<vwc-text ...=${spread(args)}>
+ The quick brown fox jumps over the lazy dog
+</vwc-text>`;
+
+export const Basic = Template.bind({});
+Basic.args = { 'font-face': VVDFontFace.Headline1 };

components/text/test/text.a11y.test.js

@@ -0,0 +1,23 @@
+import '../vwc-text.js';
+import {
+ isolatedElementsCreation,
+ textToDomToParent
+} from '../../../test/test-helpers.js';
+import { chaiA11yAxe } from 'chai-a11y-axe';
+
+chai.use(chaiA11yAxe);
+
+const COMPONENT_NAME = 'vwc-text';
+
+describe(`${COMPONENT_NAME} a11y`, () => {
+ const addElement = isolatedElementsCreation();
+
+ it('should have 0 accessibility violations containing semantic tag', async () => {
+ const [actualElement] = addElement(
+ textToDomToParent(`<${COMPONENT_NAME}><h1>Lorem ipsum dolor sit amet</h1></${COMPONENT_NAME}>`)
+ );
+ await actualElement.updateComplete;
+
+ await expect(actualElement).shadowDom.to.be.accessible();
+ });
+});