Merge pull request #106 from liip/feature/bds#348-form-documentation

Feature/bds#348 form documentation

app/components/ch/components/Checkbox.vue

@@ -6,13 +6,14 @@
       :id="id"
       :name="name"
       :value="value"
+      :required="required"
     />
     <label
       v-if="label"
       :for="id"
       :class="labelClasses"
     >
-      {{ label }}
+      {{ label }} <span v-if="required" class="sr-only">required</span>
     </label>
     <div v-if="message" class="badge badge--sm" :class="`badge--${messageType}`">
       {{ message }}
@@ -51,7 +52,10 @@ export default {
     messageType: {
       type: String,
       validator: (prop) => ['error', 'warning', 'success', 'info'].includes(prop),
-      default: 'error'
+    },
+    required: {
+      type: Boolean,
+      default: false,
     },
   },
 
@@ -60,13 +64,14 @@ export default {
       let base = 'input '
       if (this.variant) base += `input--${this.variant} `
       if (this.size) base += `input--${this.size} `
-      if (this.message) base += `input--${this.messageType} `
+      if (this.messageType) base += `input--${this.messageType} `
       return base
     },
     labelClasses() {
       let base = ''
       if (this.variant === 'negative') base += `text--negative `
       if (this.size) base += `text--${this.size} `
+      if (this.required) base += `text--asterisk `
       return base
     },
   },

app/components/ch/components/Fieldset.vue

@@ -0,0 +1,65 @@
+<template>
+  <fieldset class="form__group">
+    <legend
+      v-if="legend"
+      class="form__group__legend"
+      :class="legendClasses"
+    >
+      {{ legend }} <span v-if="required" class="sr-only">required</span>
+    </legend>
+    <slot />
+    <div v-if="message" class="badge badge--sm" :class="`badge--${messageType}`">
+      {{ message }}
+    </div>
+  </fieldset>
+</template>
+
+<script>
+
+export default {
+  name: 'Fieldset',
+  props: {
+    variant: {
+      type: String,
+      validator: (prop) => ['outline', 'negative'].includes(prop),
+      default: 'outline'
+    },
+    size: {
+      type: String,
+      validator: (prop) => ['sm', 'base', 'lg'].includes(prop),
+    },
+    legend: {
+      type: String,
+    },
+    message: {
+      type: String,
+    },
+    messageType: {
+      type: String,
+      validator: (prop) => ['error', 'warning', 'success', 'info'].includes(prop),
+      default: 'error'
+    },
+    required: {
+      type: Boolean,
+      default: false,
+    },
+  },
+
+  computed: {
+    classes() {
+      let base = 'input '
+      if (this.variant) base += `input--${this.variant} `
+      if (this.size) base += `input--${this.size} `
+      if (this.message) base += `input--${this.messageType} `
+      return base
+    },
+    legendClasses() {
+      let base = ''
+      if (this.variant === 'negative') base += `text--negative `
+      if (this.size) base += `text--${this.size} `
+      if (this.required) base += `text--asterisk `
+      return base
+    },
+  },
+}
+</script>

app/components/ch/components/Input.vue

@@ -5,7 +5,8 @@
       :for="id"
       :class="labelClasses"
     >
-      {{ label }}
+      {{ label }}<span v-if="required" class="form__group__required" />
+      {{ message }}
     </label>
     <input
       :type="type"
@@ -20,6 +21,7 @@
       :pattern="pattern"
       :autocomplete="autocomplete"
       :readonly=readonly
+      :required="required"
     />
     <div v-if="message" class="badge badge--sm" :class="`badge--${messageType}`">
       {{ message }}
@@ -88,6 +90,10 @@ export default {
       type: Boolean,
       default: false,
     },
+    required: {
+      type: Boolean,
+      default: false,
+    },
   },
 
   computed: {
@@ -103,6 +109,7 @@ export default {
       if (this.variant === 'negative') base += `text--negative `
       if (this.size) base += `text--${this.size} `
       if (this.hideLabel) base += `sr-only `
+      if (this.required) base += `text--asterisk `
       return base
     },
   },

app/components/ch/components/Radio.vue

@@ -7,14 +7,14 @@
       :name="name"
       :value="value"
       :checked="checked"
-
+      :required="required"
     />
     <label
       v-if="label"
       :for="id"
       :class="labelClasses"
     >
-      {{ label }}
+      {{ label }} <span v-if="required" class="sr-only">required</span>
     </label>
     <div v-if="message" class="badge badge--sm" :class="`badge--${messageType}`">
       {{ message }}
@@ -56,7 +56,10 @@ export default {
     messageType: {
       type: String,
       validator: (prop) => ['error', 'warning', 'success', 'info'].includes(prop),
-      default: 'error'
+    },
+    required: {
+      type: Boolean,
+      default: false,
     },
   },
 
@@ -65,13 +68,14 @@ export default {
       let base = 'input '
       if (this.variant) base += `input--${this.variant} `
       if (this.size) base += `input--${this.size} `
-      if (this.message) base += `input--${this.messageType} `
+      if (this.messageType) base += `input--${this.messageType} `
       return base
     },
     labelClasses() {
       let base = ''
       if (this.variant === 'negative') base += `text--negative `
       if (this.size) base += `text--${this.size} `
+      if (this.required) base += `text--asterisk `
       return base
     },
   },

app/components/ch/components/Select.vue

@@ -5,13 +5,14 @@
       :for="id"
       :class="labelClasses"
     >
-      {{ label }}
+      {{ label }}<span v-if="required" class="form__group__required" />
     </label>
     <div :class="selectWrapperClasses">
       <select
         :class="selectClasses"
         :id="id"
         :name="name"
+        :required="required"
       >
         <slot></slot>
       </select>
@@ -69,7 +70,10 @@ export default {
     messageType: {
       type: String,
       validator: (prop) => ['error', 'warning', 'success', 'info'].includes(prop),
-      default: 'error'
+    },
+    required: {
+      type: Boolean,
+      default: false,
     },
   },
 
@@ -83,14 +87,15 @@ export default {
       let base = ''
       if (this.variant) base += `input--${this.variant} `
       if (this.size) base += `input--${this.size} `
-      if (this.message) base += `input--${this.messageType} `
+      if (this.messageType) base += `input--${this.messageType} `
       return base
     },
     labelClasses() {
       let base = ''
       if (this.variant === 'negative') base += `text--negative `
       if (this.size) base += `text--${this.size} `
       if (this.hideLabel) base += `sr-only `
+      if (this.required) base += `text--asterisk `
       return base
     },
   },

app/components/ch/components/Textarea.vue

@@ -14,6 +14,7 @@
       :rows="rows"
       :cols="cols"
       :placeholder="placeholder"
+      :required="required"
     >
     </textarea>
     <div v-if="message" class="badge badge--sm" :class="`badge--${messageType}`">
@@ -60,7 +61,10 @@ export default {
     messageType: {
       type: String,
       validator: (prop) => ['error', 'warning', 'success', 'info'].includes(prop),
-      default: 'error'
+    },
+    required: {
+      type: Boolean,
+      default: false,
     },
   },
 
@@ -69,13 +73,14 @@ export default {
       let base = ''
       if (this.variant) base += `input--${this.variant} `
       if (this.size) base += `input--${this.size} `
-      if (this.message) base += `input--${this.messageType} `
+      if (this.messageType) base += `input--${this.messageType} `
       return base
     },
     labelClasses() {
       let base = ''
       if (this.variant === 'negative') base += `text--negative `
       if (this.size) base += `text--${this.size} `
+      if (this.required) base += `text--asterisk `
       return base
     },
   },

app/components/ch/sections/FormDemo.vue

@@ -52,6 +52,22 @@
         <Input type="url" id="url-id" label="Input type url" placeholder="Placeholder" />
         <Input type="week" id="week-id" label="Input type week" placeholder="Placeholder" />
       </div>
+
+      <div class="form">
+        <h2 class="h2 mt-8">required fields example</h2>
+        <div class="form__group">
+          <Input type="text" id="text-id-0" label="Input type text" placeholder="Placeholder" required />
+        </div>
+        <div class="form__group">
+          <Select label="Select" id="select" required>
+            <option disabled selected>Choose your country</option>
+            <option>Switzerland</option>
+            <option>Swaziland</option>
+            <option>Sweden</option>
+          </Select>
+        </div>
+      </div>
+
     </div>
   </div>
 </template>
@@ -71,4 +87,4 @@ export default {
     Checkbox
   }
 }
-</script>
+</script>

app/components/stories/components/Checkbox.stories.mdx

@@ -25,7 +25,19 @@ import Checkbox from '../../ch/components/Checkbox.vue'
 export const Template = (args, { argTypes }) => ({
   props: Object.keys(argTypes),
   components: { Checkbox },
-  template: '<Checkbox :variant="variant" :size="size" :label="label" :id="id" :name="name" :value="value" :message="message" :messageType="messageType" />',
+  template: `
+    <Checkbox
+      :variant="variant"
+      :size="size"
+      :label="label"
+      :id="id"
+      :name="name"
+      :value="value"
+      :message="message"
+      :messageType="messageType"
+      :required="required"
+    />
+  `,
 })
 
 # Input Checkbox
@@ -85,3 +97,54 @@ For size variations, the following css classes are built:
   />
   <input type="checkbox" class="input--outline input--lg" value="input--lg" />
 </Canvas>
+
+
+## Required checkbox
+
+If the field is mandatory:
+- a `required` attribute is added to the input element
+- an asterisk is displayed right after the label. This can be done by adding a `text--asterisk` class on the label element.
+- the word “required“ is added to the legend for screen readers. This can be done by wrapping the word into a `.sr-only` element.
+
+<Canvas>
+<div class="form__group__checkbox">
+  <input
+    type="checkbox"
+    id="checkbox-id1"
+    name="checkbox-name"
+    required="required"
+    class="input input--outline input--base"
+    value=""
+  />
+  <label for="checkbox-id1" class="text--base text--asterisk">
+    Label <span class="sr-only">required</span>
+  </label>
+</div>
+</Canvas>
+
+## Messages
+
+If the field has error, an `input--error` class is added to the input element. Additionally
+a `badge badge--sm badge--error` element wraps the error message, right after the input element:
+
+<Canvas>
+<div class="form__group__checkbox">
+  <input
+    type="checkbox"
+    id="checkbox-id2"
+    name="checkbox-name"
+    required="required"
+    class="input input--outline input--base input--error"
+    value=""
+  />
+  <label for="checkbox-id2" class="text--base text--asterisk">
+    Label <span class="sr-only">required</span>
+  </label>
+  <div class="badge badge--sm badge--error">Error message</div>
+</div>
+</Canvas>
+
+
+## Multiple Checkboxes
+It's recommanded to wrap related checkboxes in a `fieldset` element, with a `legend` element as a title.
+Check the [Fieldset documentation](/docs/components-form-fieldset--example-radio) for more information.