feat(vwc-menu): issue #592 menu docs and better stories (#596)

* issue #592: menu docs and better stories * issue #592: fixing some typos * adding the docs to the select * adding select documentation * adding select documentation * issue #592: docs for menu and more * issue #592: docs for menu and more * adding an initial content fo volta to vivid migration
Vonage · Feb 2, 2021 · 67dbda5 · 67dbda5
1 parent 7cdf9ff
commit 67dbda5
Show file tree

Hide file tree

Showing 14 changed files with 195 additions and 27 deletions.
diff --git a/.storybook/build-scripts/create-stories-from-md.mjs b/.storybook/build-scripts/create-stories-from-md.mjs
@@ -5,6 +5,7 @@ import { dirname, resolve } from 'path';
 import { performance } from 'perf_hooks';
 import glob from 'glob';
 import showdown from 'showdown';
+import showdownHtmlEscape from 'showdown-htmlescape';
 
 export default build;
 
@@ -17,7 +18,7 @@ const CONFIGS_LOOKUP_PATTERN = '+(common|components|docs)/**/stories/**/*.config
 const DEFAULT_OUTPUT_FILE_SUFFIX = '.autogenerated.stories.js';
 
 const FS_OPTIONS = { encoding: 'utf-8' };
-const converter = new showdown.Converter();
+const converter = new showdown.Converter({ extensions: [showdownHtmlEscape] });
 converter.setFlavor('github');
 
 async function build() {
@@ -27,7 +28,7 @@ async function build() {
 	for (const configPath of configPaths) {
 		await processJsConfiguration(configPath);
 	}
-	console.log(`... transformation of MDs to stories DONE (${Math.round(performance.now() - startTime)}ms)${os.EOL}`);
+	console.log(`... transformation of ${configPaths.length} MDs to stories DONE (${Math.round(performance.now() - startTime)}ms)${os.EOL}`);
 }
 
 function collectConfigurations() {

diff --git a/common/context/src/partials/_layout.scss b/common/context/src/partials/_layout.scss
@@ -33,12 +33,12 @@
 			padding: 20px 22px;
 			border-radius: 6px;
 
-			:first-child {
+			> :first-child {
 				margin-block-start: 0;
 				padding-block-start: 0;
 			}
 
-			:last-child {
+			> :last-child {
 				margin-block-end: 0;
 				padding-block-end: 0;
 			}

diff --git a/.../context/stories/context-basic.config.mjs → ...t/stories/context-introduction.config.mjs b/.../context/stories/context-basic.config.mjs → ...t/stories/context-introduction.config.mjs
@@ -1,9 +1,9 @@
 export default {
 	sourcePath: '../readme.md',
-	outputName: 'context-basic',
+	outputName: 'context-introduction',
 	story: {
-		title: 'Core/Context',
-		name: 'Context',
+		title: 'Core/Context/Introduction',
+		name: 'Introduction',
 		parameters: {
 			options: {
 				showPanel: false,

diff --git a/components/menu/readme.md b/components/menu/readme.md
@@ -1,6 +1,40 @@
-# vwc-menu
+# `vwc-menu`
 
-This component is an extension of [<mwc-menu>](https://github.com/material-components/material-components-web-components/tree/master/packages/menu)
+`vwc-menu` is a surfacing menu component, showing up on demand, eg upon user action.
+`vwc-menu` fetured with an internal list, while all LightDOM elements of it become children of that list.
+
+> This component is an extension of [\<mwc-menu\>](https://github.com/material-components/material-components-web-components/tree/master/packages/menu).
+
+# Usage
+
+Usage example:
+```html
+<vwc-menu>
+	<vwc-list-item>Item 1</vwc-list-item>
+	<vwc-list-item>Item 2</vwc-list-item>
+	<vwc-list-item>Item 3</vwc-list-item>
+	<vwc-list-item>Item 4</vwc-list-item>
+</vwc-menu>
+```
+
+`vwc-list-item` should be used for the menu items, putting any of you custom content within, including rich HTML if needed.
+
+> It is still consumer's responsibility to initiate `vwc-list-item`, as any other Vivid component.
+
+Initiate `vwc-menu` to be available in your component/application:
+```javascript
+import '@vonage/vwc-menu';
+
+//	or, to be able to use casting in TypeScript, do
+
+import { VWCMenu } from '@vonage/vwc-menu';
+
+import '@vonage/vwc-list/vwc-list-item.js';
+```
+
+# API
+
+`vwc-menu` exposes several APIs to provide its fuctionality, namely properties, methods and events.
 
 ## Properties
 
@@ -12,14 +46,11 @@ This component is an extension of [<mwc-menu>](https://github.com/material-compo
 | `corner`                  |           | `"TOP_LEFT" \| "TOP_RIGHT" \| "BOTTOM_LEFT" \| "BOTTOM_RIGHT" \| "TOP_START" \| "TOP_END" \| "BOTTOM_START" \| "BOTTOM_END"` |                                                  |
 | `defaultFocus`            |           | `"NONE" \| "LIST_ROOT" \| "FIRST_ITEM" \| "LAST_ITEM"` |                                                  |
 | `fixed`                   |           | `boolean`                                        |                                                  |
-| `floatingLabelFoundation` |           | `MDCFloatingLabelFoundation \| undefined`        |                                                  |
 | `forceGroupSelection`     |           | `boolean`                                        |                                                  |
 | `fullwidth`               |           | `boolean`                                        |                                                  |
 | `index`                   | readonly  | `MWCListIndex`                                   |                                                  |
 | `innerRole`               |           | `"menu" \| "listbox"`                            |                                                  |
 | `items`                   | readonly  | `ListItemBase[]`                                 |                                                  |
-| `lineRippleFoundation`    |           | `MDCLineRippleFoundation \| undefined`           |                                                  |
-| `mdcRoot`                 |           | `MenuSurface`                                    | Root element for MDC Foundation usage.<br /><br />Define in your component with the `@query` decorator |
 | `menuCorner`              |           | `MenuCorner`                                     |                                                  |
 | `multi`                   |           | `boolean`                                        |                                                  |
 | `open`                    |           | `boolean`                                        |                                                  |

diff --git a/components/menu/stories/menu-all.stories.js b/components/menu/stories/menu-all.stories.js
@@ -11,6 +11,6 @@ export default {
 	argTypes
 }
 
-export { Basic } from './menu-basic.js';
+export { WithVWCListItem, WithVWCListItemComplex } from './menu-basic.js';
 
-// export { cascading } from './menu-cascading.js';
+// export { Cascading } from './menu-cascading.js';
diff --git a/components/menu/stories/menu-basic.js b/components/menu/stories/menu-basic.js
@@ -1,22 +1,49 @@
 import { html } from 'lit-element';
 import { spread } from '@open-wc/lit-helpers';
 
-const Template = args => html`
+const TemplateA = args => html`
 	<div style="position: relative">
 		<vwc-button id="button" label="Open menu" @click="${anchorClickHandler}"></vwc-button>
-		<vwc-menu id="menu" ...=${spread(args)}>
+		<vwc-menu id="menu" ...=${spread(args)} @selected="${onMenuSelected}">
 			<vwc-list-item>Basic item 1</vwc-list-item>
 			<vwc-list-item>Basic item 2</vwc-list-item>
 			<vwc-list-item>Basic item 3</vwc-list-item>
 			<vwc-list-item>Basic item 4</vwc-list-item>
 		</vwc-menu>
-	</div>`;
+	</div>
+`;
 
-export const Basic = Template.bind({});
+export const WithVWCListItem = TemplateA.bind({});
+
+const TemplateB = args => html`
+	<div style="position: relative">
+		<vwc-button id="button" label="Open menu" @click="${anchorClickHandler}"></vwc-button>
+		<vwc-menu id="menu" ...=${spread(args)} @selected="${onMenuSelected}">
+			<vwc-list-item>
+				<div>Basic item 1</div>
+			</vwc-list-item>
+			<vwc-list-item>
+				<div>Basic item 2</div>
+			</vwc-list-item>
+			<vwc-list-item>
+				<div>Basic item 3</div>
+			</vwc-list-item>
+			<vwc-list-item>
+				<div>Basic item 4</div>
+			</vwc-list-item>
+		</vwc-menu>
+	</div>
+`;
+
+export const WithVWCListItemComplex = TemplateB.bind({});
 
 function anchorClickHandler() {
 	const anchor = document.querySelector('#button');
 	const menu = document.querySelector('#menu');
 	menu.anchor = anchor;
 	menu.open = true;
 }
+
+function onMenuSelected(e) {
+	console.log(e.detail);
+}
diff --git a/components/menu/stories/menu-cascading.js b/components/menu/stories/menu-cascading.js
@@ -1,6 +1,6 @@
 import { html } from 'lit-element';
 
-export const cascading = () => html`
+export const Cascading = () => html`
 	<div style="position: relative">
 		<vwc-fab id="context-menu-anchor" style="display: inline-flex" mini icon="more_vert" @click="${anchorAClickHandler}"></vwc-fab>
 		<vwc-menu id="context-menu-base">

diff --git a/components/menu/stories/menu-introduction.config.mjs b/components/menu/stories/menu-introduction.config.mjs
@@ -0,0 +1,14 @@
+export default {
+	sourcePath: '../readme.md',
+	outputName: 'menu-introduction',
+	story: {
+		title: 'Components/Atoms/Menu/Introduction',
+		name: 'Introduction',
+		parameters: {
+			options: {
+				showPanel: false,
+				isToolshown: false
+			}
+		}
+	}
+};
diff --git a/components/select/readme.md b/components/select/readme.md
@@ -1,28 +1,59 @@
-# vwc-select
+# `vwc-select`
 
-This component is an extension of [<mwc-select>](https://github.com/material-components/material-components-web-components/tree/master/packages/select)
+`vwc-select` is a drop-down kind of input element.
+
+> This component is an extension of [\<mwc-select\>](https://github.com/material-components/material-components-web-components/tree/master/packages/select).
+
+# Usage
+
+Import the component in your context, to get it initialized:
+```js
+import '@vonage/vwc-select/vwc-select.js';
+
+//	or, to be able to use casting in TypeScript, do
+
+import { VWCSelect } from '@vonage/vwc-select/vwc-select.js';
+
+import '@vonage/vwc-list/vwc-list-item.js';
+```
+
+We suggest as a rule of thumb to use `vwc-list-item` component to provide the list of options.
+`vwc-list-item` is capable of holding any content, from simple text to rich HTML.
+
+The following should provide you with a working example:
+```html
+<vwc-select outlined label="VWC Select" helper="Helper text">
+	<vwc-list-item></vwc-list-item>
+	<vwc-list-item value="0">Item 0</vwc-list-item>
+	<vwc-list-item value="1">Item 1</vwc-list-item>
+</vwc-select>
+```
+
+Few points to pay attention to, in order to get the expected result:
+* Select will preselect the first item in the list (much like the native HTML select), so if one would like to start with empty value, stare the list with an empty item
+* Items MUST HAVE an attribute value with an actual values that you'd like to use in your applicative logic (except the empty choice);
+the text/content within the items is for **labeling** purposes only, should be considered as not logically reliable (think of localization down the road, or some rich HTML)
+
+# API
+
+`vwc-select` exposes the following properties, methods and events:
 
 ## Properties
 
 | Property                  | Modifiers | Type                                             | Description                                      |
 |---------------------------|-----------|--------------------------------------------------|--------------------------------------------------|
 | `disabled`                |           | `boolean`                                        |                                                  |
-| `floatingLabelFoundation` |           | `MDCFloatingLabelFoundation \| undefined`        |                                                  |
 | `helper`                  |           | `string`                                         |                                                  |
 | `icon`                    |           | `string`                                         |                                                  |
 | `index`                   | readonly  | `number`                                         |                                                  |
 | `items`                   | readonly  | `ListItemBase[]`                                 |                                                  |
 | `label`                   |           | `string`                                         |                                                  |
-| `lineRippleFoundation`    |           | `MDCLineRippleFoundation \| undefined`           |                                                  |
 | `naturalMenuWidth`        |           | `boolean`                                        |                                                  |
 | `outlined`                |           | `boolean`                                        |                                                  |
 | `required`                |           | `boolean`                                        |                                                  |
-| `ripple`                  | readonly  | `RippleInterface \| Promise<RippleInterface \| null> \| undefined` | Implement ripple getter for Ripple integration with mwc-formfield |
 | `selected`                | readonly  | `ListItemBase \| null`                           |                                                  |
 | `validateOnInitialRender` |           | `boolean`                                        |                                                  |
 | `validationMessage`       |           | `string`                                         |                                                  |
-| `validity`                | readonly  | `ValidityState`                                  |                                                  |
-| `validityTransform`       |           | `((value: string, nativeValidity: ValidityState) => Partial<ValidityState>) \| null` |                                                  |
 | `value`                   |           | `string`                                         |                                                  |
 
 ## Methods

diff --git a/components/select/stories/select-introduction.config.mjs b/components/select/stories/select-introduction.config.mjs
@@ -0,0 +1,14 @@
+export default {
+	sourcePath: '../readme.md',
+	outputName: 'select-introduction',
+	story: {
+		title: 'Components/Atoms/Select/Introduction',
+		name: 'Introduction',
+		parameters: {
+			options: {
+				showPanel: false,
+				isToolshown: false
+			}
+		}
+	}
+};
diff --git a/docs/stories/guides/context-volta-to-vivid.config.mjs b/docs/stories/guides/context-volta-to-vivid.config.mjs
@@ -0,0 +1,24 @@
+import {
+	hrefLinkProcessing
+} from '../../../.storybook/build-scripts/create-stories-from-md.mjs';
+
+export default {
+	sourcePath: '../../volta-to-vivid.md',
+	outputName: 'context-volta-to-vivid',
+	story: {
+		title: 'Guides/Volta To Vivid Migration',
+		name: 'VoltaToVividMigration',
+		parameters: {
+			options: {
+				showPanel: false,
+				isToolshown: false
+			}
+		}
+	},
+	htmlPostProcess: htmlText => {
+		return hrefLinkProcessing(htmlText, [
+			['href="../readme.md"', '?path=/story/introduction-meet-vivid--meet-vivid'],
+			['href="./architecture.md"', '?path=/story/introduction-architecture--architecture']
+		]);
+	}
+};
diff --git a/docs/volta-to-vivid.md b/docs/volta-to-vivid.md
@@ -0,0 +1,18 @@
+# Summary
+
+[Back to main page](../readme.md)
+
+This page is called to concentrate few most useful and widely relevant tips and recipes for migrating the existing Vonage front end applications to Vivid.
+
+# Typography
+
+## Headers
+
+Headers in Vivid got size upscale to provide more flexibility and options.
+Therefore, any existing header level `X` in the Volta based application should be changed to header `X+2`:
+| Volta | Vivid |
+|-------|-------|
+| `h1`  | `h3`  |
+| `h2`  | `h4`  |
+| `h3`  | `h5`  |
+| `h4`  | `h6`  |
diff --git a/package.json b/package.json
@@ -111,6 +111,7 @@
 		"semver-compare": "^1.0.0",
 		"semver-diff": "^3.1.1",
 		"showdown": "^1.9.1",
+		"showdown-htmlescape": "^0.1.9",
 		"spech": "^0.2.1",
 		"standard-version": "^9.1.0",
 		"tar-stream": "^2.1.4",

diff --git a/yarn.lock b/yarn.lock
@@ -15142,7 +15142,14 @@ shelljs@^0.8.3, shelljs@^0.8.4:
     interpret "^1.0.0"
     rechoir "^0.6.2"
 
-showdown@^1.9.1:
+showdown-htmlescape@^0.1.9:
+  version "0.1.9"
+  resolved "https://vonagecc.jfrog.io/vonagecc/api/npm/npm/showdown-htmlescape/-/showdown-htmlescape-0.1.9.tgz#4299676a209016c9fbdabe60c38408eef3eb1800"
+  integrity sha1-QplnaiCQFsn72r5gw4QI7vPrGAA=
+  dependencies:
+    showdown "^1.2.3"
+
+showdown@^1.2.3, showdown@^1.9.1:
   version "1.9.1"
   resolved "https://vonagecc.jfrog.io/vonagecc/api/npm/npm/showdown/-/showdown-1.9.1.tgz#134e148e75cd4623e09c21b0511977d79b5ad0ef"
   integrity sha1-E04UjnXNRiPgnCGwURl315ta0O8=