From 0bf891d3ae6f84f655d7ee74acdd166ab5ba2615 Mon Sep 17 00:00:00 2001
From: Nate Wright <natew@notthisway.com>
Date: Thu, 24 May 2018 17:50:28 +0100
Subject: [PATCH] pkp/pkp-lib#3594 Initial implementation of Form component

---
 src/components/Form/Form.vue             | 116 +++++++++++++++++++
 src/components/Form/FormGroup.vue        | 122 ++++++++++++++++++++
 src/components/Form/FormPage.vue         |  86 ++++++++++++++
 src/components/Form/fields/FieldBase.vue | 140 +++++++++++++++++++++++
 src/components/Form/fields/FieldText.vue |  50 ++++++++
 src/docs/examples.js                     |   8 ++
 src/docs/examples/Form/data.js           |  84 ++++++++++++++
 src/docs/examples/Form/notes.md          |   2 +
 src/main.js                              |  10 ++
 9 files changed, 618 insertions(+)
 create mode 100644 src/components/Form/Form.vue
 create mode 100644 src/components/Form/FormGroup.vue
 create mode 100644 src/components/Form/FormPage.vue
 create mode 100644 src/components/Form/fields/FieldBase.vue
 create mode 100644 src/components/Form/fields/FieldText.vue
 create mode 100644 src/docs/examples/Form/data.js
 create mode 100644 src/docs/examples/Form/notes.md

diff --git a/src/components/Form/Form.vue b/src/components/Form/Form.vue
new file mode 100644
index 000000000..d7bfb91b6
--- /dev/null
+++ b/src/components/Form/Form.vue
@@ -0,0 +1,116 @@
+<template>
+	<form
+		method="POST"
+		class="pkpForm -pkpClearfix"
+		:action="action"
+	>
+		<form-page v-for="page in pages"
+			:key="page.id"
+			:id="page.id"
+			:submitOnNext="page.submitOnNext"
+			:groups="groups"
+			:fields="fields"
+			:formId="id"
+			:activeLocales="activeLocales"
+			:availableLocales="availableLocales"
+			@toggleLocale="toggleLocale"
+			@change="fieldChanged"
+		/>
+		<div v-if="submitButton" class="pkpForm__buttons">
+			<pkp-button
+				:label="submitButton.label"
+				:isPrimary="submitButton.isPrimary"
+				:isWarnable="submitButton.isWarnable"
+				:isLink="submitButton.isLink"
+				:isActive="submitButton.isActive"
+				:withicon="submitButton.withicon"
+				@click.prevent.stop="submit"
+			/>
+		</div>
+	</form>
+</template>
+
+<script>
+import FormPage from './FormPage.vue';
+import PkpButton from '@/components/Button/Button.vue';
+
+export default {
+	name: 'Form',
+	components: {
+		FormPage,
+		PkpButton,
+	},
+	data: function () {
+		return {
+			id: '',
+			action: '',
+			errors: [],
+			object: null,
+			fields: [],
+			groups: [],
+			pages: [],
+			submitButton: null,
+			activeLocales: [],
+		};
+	},
+	computed: {
+		/**
+		 * Available form locales
+		 *
+		 * @return array
+		 */
+		availableLocales: function () {
+			return $.pkp.app.formLocales;
+		},
+	},
+	methods: {
+		/**
+		 * Submit the form
+		 */
+		submit: function () {
+			console.log('submit');
+		},
+
+		/**
+		 * Change the locale
+		 *
+		 * @param string localeKey (eg - "en_US")
+		 */
+		toggleLocale: function (localeKey) {
+			if (this.activeLocales.includes(localeKey)) {
+				this.activeLocales.splice(this.activeLocales.indexOf(localeKey), 1);
+			} else {
+				this.activeLocales.push(localeKey);
+			}
+		},
+
+		/**
+		 * Update values when a field has changed
+		 *
+		 * @param object data {{
+		 *  @option string name Field name
+		 *  @option string value New value
+		 *  @option string localeKey Locale key for this value. Empty it not multilingual
+		 * }}
+		 */
+		fieldChanged: function (data) {
+			console.log('field changed', data);
+		},
+	},
+	mounted: function () {
+
+		// Set the current locale
+		if (!this.activeLocales.length) {
+			this.activeLocales = [this.availableLocales[0].key];
+		}
+	},
+};
+</script>
+
+<style lang="less">
+@import '../../styles/_import';
+
+.pkpForm__buttons {
+	padding: @base;
+}
+</style>
diff --git a/src/components/Form/FormGroup.vue b/src/components/Form/FormGroup.vue
new file mode 100644
index 000000000..9ae66c1e3
--- /dev/null
+++ b/src/components/Form/FormGroup.vue
@@ -0,0 +1,122 @@
+<template>
+	<fieldset class="pkpFormGroup -pkpClearfix">
+		<div v-if="label" class="pkpFormGroup__heading">
+			<legend class="pkpFormGroup__legend">{{ label }}</legend>
+			<div v-if="description" class="pkpFormGroup__description" v-html="description"></div>
+		</div>
+		<div class="pkpFormGroup__fields">
+			<template v-for="field in fieldsInGroup">
+				<template v-if="field.isMultilingual">
+					<div v-for="locale in availableLocales" class="pkpFormGroup__locale" :class="{'-isActive': activeLocales.includes(locale)}">
+						<component
+							:is="field.component"
+							v-bind="field"
+							:localeKey="locale.key"
+							:formId="formId"
+							@change="fieldChanged"
+						></component>
+					</div>
+				</template>
+				<template v-else>
+					<component
+						:is="field.component"
+						v-bind="field"
+						:formId="formId"
+						@change="fieldChanged"
+					></component>
+				</template>
+			</template>
+		</div>
+	</fieldset>
+</template>
+
+<script>
+import FieldText from '@/components/Form/fields/FieldText.vue';
+
+export default {
+	name: 'FormGroup',
+	components: {
+		FieldText,
+	},
+	props: {
+		id: String,
+		label: [String, Object],
+		description: [String, Object],
+		pageId: String,
+		fields: Array,
+		formId: String,
+		activeLocales: Array,
+		availableLocales: Array,
+	},
+	computed: {
+		/**
+		 * All fields assigned to this group
+		 *
+		 * @return array
+		 */
+		fieldsInGroup: function () {
+			return this.fields.filter(field => field.groupId === this.id);
+		},
+
+		/**
+		 * Are there any multilingual fields in this group?
+		 *
+		 * @return boolean
+		 */
+		isMultilingual: function () {
+			return this.availableLocales.length > 1 &&
+				this.fieldsInGroup.find((field) => field.isMultilingual === true);
+		},
+	},
+	methods: {
+		/**
+		 * Emit an event when a field's value has changed
+		 *
+		 * @param object data {{
+		 *  @option string name Field name
+		 *  @option string value New value
+		 *  @option string localeKey Locale key for this value. Empty it not multilingual
+		 * }}
+		 */
+		fieldChanged: function (data) {
+			this.$emit('change', data);
+		},
+	},
+};
+</script>
+
+<style lang="less">
+@import '../../styles/_import';
+
+.pkpFormGroup {
+	position: relative;
+	padding: @base;
+	border: none;
+}
+
+.pkpFormGroup__heading {
+	float: left;
+	width: 30%;
+	padding-right: 1.5rem;
+	line-height: @line-sml;
+
+	+ .pkpFormGroup__fields {
+		float: right;
+		width: 70%;
+		padding-left: 1.5rem;
+	}
+}
+
+.pkpFormGroup__legend {
+	display: inline-block;
+	font-weight: @bold;
+}
+
+.pkpFormGroup__description {
+	font-size: @font-sml;
+}
+
+.pkpFormGroup .pkpFormField + .pkpFormField {
+	margin-top: @base + @half;
+}
+</style>
diff --git a/src/components/Form/FormPage.vue b/src/components/Form/FormPage.vue
new file mode 100644
index 000000000..38e8328f4
--- /dev/null
+++ b/src/components/Form/FormPage.vue
@@ -0,0 +1,86 @@
+<template>
+	<div class="pkpFormPage">
+		<div v-if="isMultilingual" class="pkpFormPage__locales">
+			<pkp-button v-for="locale in availableLocales"
+				:key="locale.key"
+				:label="locale.label"
+				@click.prevent.stop="toggleLocale(locale.key)"
+			/>
+		</div>
+		<form-group v-for="group in groupsInPage"
+			:key="group.id"
+			v-bind="group"
+			:fields="fields"
+			:activeLocales="activeLocales"
+			:availableLocales="availableLocales"
+			@change="fieldChanged"
+		/>
+	</div>
+</template>
+
+<script>
+import FormGroup from '@/components/Form/FormGroup.vue';
+import PkpButton from '@/components/Button/Button.vue';
+
+export default {
+	name: 'FormPage',
+	components: {
+		FormGroup,
+		PkpButton,
+	},
+	props: {
+		id: String,
+		submitOnNext: {
+			type: Boolean,
+			default: false,
+		},
+		groups: Array,
+		fields: Array,
+		activeLocales: Array,
+		availableLocales: Array,
+	},
+	computed: {
+		/**
+		 * All groups assigned to this page
+		 *
+		 * @return array
+		 */
+		groupsInPage: function () {
+			return this.groups.filter(group => group.pageId === this.id);
+		},
+
+		/**
+		 * All assigned to groups on this page
+		 *
+		 * @return array
+		 */
+		fieldsInPage: function () {
+			return this.fields.filter(field => this.groupsInPage.includes(this.fields.groupId));
+		},
+
+		/**
+		 * Are there any multilingual fields on this page?
+		 *
+		 * @return boolean
+		 */
+		isMultilingual: function () {
+			return this.availableLocales.length > 1 &&
+				this.fieldsInPage.find((field) => field.isMultilingual === true);
+		},
+	},
+	methods: {
+		/**
+		 * Emit an event when a field's value has changed
+		 *
+		 * @param object data {{
+		 *  @option string name Field name
+		 *  @option string value New value
+		 *  @option string localeKey Locale key for this value. Empty it not multilingual
+		 * }}
+		 */
+		fieldChanged: function (data) {
+			this.$emit('change', data);
+		},
+	},
+};
+</script>
diff --git a/src/components/Form/fields/FieldBase.vue b/src/components/Form/fields/FieldBase.vue
new file mode 100644
index 000000000..5b428fe23
--- /dev/null
+++ b/src/components/Form/fields/FieldBase.vue
@@ -0,0 +1,140 @@
+<script>
+export default {
+	name: 'FieldBase',
+	props: {
+		name: String,
+		component: String,
+		label: [String, Object],
+		description: [String, Object],
+		tooltip: [String, Object],
+		helpLink: String,
+		groupId: String,
+		formId: String,
+		isMultilingual: Boolean,
+		isRequired: Boolean,
+		validateAs: String,
+		localeKey: String,
+		value: [String, Number, Object, Boolean],
+	},
+	computed: {
+		/**
+		 * A localized representation of the value
+		 *
+		 * If this is not a multilingual field, it is just the value, but we v-bind
+		 * to a property and emit an event for the Form to set the value
+		 */
+		localizedValue: {
+			get: function () {
+				if (this.isMultilingual) {
+					return this.localize(this.value);
+				} else {
+					return this.value;
+				}
+			},
+			set: function (newVal) {
+				this.$emit('change', {
+					name: this.name,
+					value: newVal,
+					localeKey: this.localeKey,
+				});
+			},
+		},
+
+		/**
+		 * A unique id for the label/control
+		 *
+		 * @return string
+		 */
+		controlId: function () {
+			return [this.formId, this.name, 'control'].join(',');
+		},
+
+		/**
+		 * A unique id for the tooltip
+		 *
+		 * @return string
+		 */
+		describedByTooltipId: function () {
+			return [this.formId, this.name, 'tooltip'].join(',');
+		},
+
+		/**
+		 * A unique id for the help link button
+		 *
+		 * @return string
+		 */
+		describedByHelpId: function () {
+			return [this.formId, this.name, 'help'].join(',');
+		},
+
+		/**
+		 * A unique id for the field description
+		 *
+		 * @return string
+		 */
+		describedByDescriptionId: function () {
+			return [this.formId, this.name, 'description'].join(',');
+		},
+
+		/**
+		 * IDs of the elements which describe this field, to be placed in the
+		 * aria-describedby attribute.
+		 *
+		 * @return string
+		 */
+		describedByIds: function () {
+			return [this.describedByDescriptionId, this.describedByHelpId, this.describedByTooltipId].join(' ');
+		},
+	},
+	methods: {
+		/**
+		 * Maybe localize a value. If it is not a locale object, return the string.
+		 *
+		 * @param string|object value
+		 * @param string|null localeKey
+		 * @return mixed
+		 */
+		maybeLocalize: function (value, localeKey) {
+			if (this.isMultilingual) {
+				return this.localize(value, localeKey);
+			} else {
+				return value;
+			}
+		},
+	},
+};
+</script>
+
+<style lang="less">
+@import '../../../styles/_import';
+
+.pkpFormField__heading {
+	line-height: @line-sml;
+}
+
+.pkpFormField__description {
+	font-size: @font-sml;
+}
+
+// Should be used for any text input and select fields to ensure consistency
+.pkpFormField__input {
+	display: block;
+	height: 2.5rem; // browser-compatibility for select fields
+	background-color: @lift;
+	padding: 0 0.5em;
+	font-size: @font-sml;
+	line-height: 2.5rem;
+	border: @bg-border;
+	border-radius: 2px;
+	padding: 0 1em;
+}
+
+.pkpFormField__input:hover {
+	border-color: @shade;
+}
+
+.pkpFormField__input:focus {
+	border-color: @primary;
+	box-shadow: inset 3px 0 0 @primary;
+}
+</style>
diff --git a/src/components/Form/fields/FieldText.vue b/src/components/Form/fields/FieldText.vue
new file mode 100644
index 000000000..d65fd7184
--- /dev/null
+++ b/src/components/Form/fields/FieldText.vue
@@ -0,0 +1,50 @@
+<template>
+	<div class="pkpFormField pkpFormField--text">
+		<div class="pkpFormField__heading">
+			<label :for="controlId" class="pkpFormField__label">{{ maybeLocalize(label, localeKey) }}</label>
+			<span v-if="maybeLocalize(tooltip, localeKey)" :id="describedByTooltipId" class="pkpFormField__tooltip">
+				<icon :icon="question-circle" />
+				{{ maybeLocalize(tooltip, localeKey) }}
+			</span>
+			<button v-if="helpLink" :id="describedByHelpId">
+				<icon :icon="info-circle" :inline="true" />
+				<span class="-screenReader">{{ i18n.help }}</span>
+			</button>
+		</div>
+		<div class="pkpFormField__control">
+			<input
+				class="pkpFormField__input pkpFormField__input--text"
+				v-model="localizedValue"
+				:type="inputType"
+				:id="controlId"
+				:name="name"
+				:aria-describedby="describedByIds"
+			/>
+		</div>
+		<div v-if="maybeLocalize(description, localeKey)"
+			class="pkpFormField__description"
+			v-html="maybeLocalize(description, localeKey)"
+			:id="describedByDescriptionId"
+		/>
+	</div>
+</template>
+
+<script>
+import FieldBase from './FieldBase';
+
+export default {
+	name: 'FieldText',
+	extends: FieldBase,
+	props: {
+		inputType: String,
+	},
+};
+</script>
+
+<style lang="less">
+@import '../../../styles/_import';
+
+.pkpFormField__input--text {
+	width: 20em;
+}
+</style>
diff --git a/src/docs/examples.js b/src/docs/examples.js
index 6b12b1eda..283645c72 100644
--- a/src/docs/examples.js
+++ b/src/docs/examples.js
@@ -4,6 +4,8 @@ import ViewButton from './examples/Button/ViewButton.vue';
 import ButtonRaw from '!!raw-loader!@/components/Button/Button.vue';
 import ViewIcon from './examples/Icon/ViewIcon.vue';
 import IconRaw from '!!raw-loader!@/components/Icon/Icon.vue';
+import Form from '@/components/Form/Form.vue';
+import FormRaw from '!!raw-loader!@/components/Form/Form.vue';
 import ViewList from './examples/List/ViewList.vue';
 import ViewListRaw from '!!raw-loader!./examples/List/ViewList.vue';
 import ListPanel from '@/components/ListPanel/ListPanel.vue';
@@ -24,6 +26,12 @@ export default {
 		label: 'Button',
 		url: '/components/Button',
 	},
+	Form: {
+		component: Form,
+		componentRaw: FormRaw,
+		label: 'Form',
+		url: '/components/Form',
+	},
 	Icon: {
 		component: ViewIcon,
 		componentRaw: IconRaw,
diff --git a/src/docs/examples/Form/data.js b/src/docs/examples/Form/data.js
new file mode 100644
index 000000000..826e75a23
--- /dev/null
+++ b/src/docs/examples/Form/data.js
@@ -0,0 +1,84 @@
+export default {
+	baseData: function () {
+		return {
+			id: 'viewForm',
+			action: '/example/1',
+			errors: [],
+			object: null,
+			fields: [
+				{
+					name: 'name',
+					component: 'field-text',
+					inputType: 'text',
+					label: 'Name',
+					description: 'Please enter your full name.',
+					tooltip: '',
+					helpLink: '',
+					groupId: 'identity',
+					isMultilingual: false,
+					isRequired: true,
+					validateAs: '',
+					localeKey: 'en_US',
+					value: '',
+				},
+				{
+					name: 'email',
+					component: 'field-text',
+					inputType: 'email',
+					label: 'Email',
+					description: '',
+					tooltip: '',
+					helpLink: '',
+					groupId: 'identity',
+					isMultilingual: false,
+					isRequired: true,
+					validateAs: '',
+					localeKey: 'en_US',
+					value: '',
+				},
+				{
+					name: 'affiliation',
+					component: 'field-text',
+					inputType: 'text',
+					label: 'Affiliation',
+					description: 'Please enter the institution you are affiliated with.',
+					tooltip: '',
+					helpLink: '',
+					groupId: 'identity',
+					isMultilingual: false,
+					isRequired: true,
+					validateAs: '',
+					localeKey: 'en_US',
+					value: '',
+				},
+			],
+			groups: [{
+				id: 'identity',
+				label: 'Identity',
+				description: 'Your name, email and institution will be displayed alongside any published works. We also use these details to communicate with you.',
+				pageId: 'viewForm',
+			}],
+			pages: [{
+				id: 'viewForm',
+				submitOnNext: false,
+			}],
+			submitButton: {
+				label: 'Submit',
+			},
+			activeLocales: ['en_US'],
+		};
+	},
+	dataDesc: {
+		id: 'Used internally. Do not modify.',
+	},
+	propDescription: {
+		action: 'Where the form should be submitted. It accepts a full URL (`http://...`) or an endpoint (`submissions/1`).',
+		errors: 'Array of error messages, which may be added in the server or client.',
+		object: 'Optional. Pass an object, like a submission, to populate the form field values. Object properties will be mapped to field names. So `submission.title` will be set to the value of a field named `title`.',
+		fields: 'Array of form fields.',
+		groups: 'Array of form groups. Use these to group related fields.',
+		pages: 'Array of form pages.',
+		submitButton: 'Object representing the submit button. Pass any props supported by `<pkp-button>`.',
+		activeLocales: 'The locale(s) the form is currently being presented in.',
+	},
+};
diff --git a/src/docs/examples/Form/notes.md b/src/docs/examples/Form/notes.md
new file mode 100644
index 000000000..7c7bf94eb
--- /dev/null
+++ b/src/docs/examples/Form/notes.md
@@ -0,0 +1,2 @@
+
+Use this component to display a form.
diff --git a/src/main.js b/src/main.js
index 85896ad1c..6f2014f7b 100644
--- a/src/main.js
+++ b/src/main.js
@@ -62,6 +62,16 @@ window.$.pkp = {
 	app: {
 		currentLocale: 'en_US',
 		primaryLocale: 'en_US',
+		formLocales: [
+			{
+				key: 'en_US',
+				label: 'English',
+			},
+			{
+				key: 'fr_CA',
+				label: 'Français (Canada)',
+			},
+		],
 	},
 };