Merge branch 'hb/feat/form-elements-docs' of https://github.com/wmcad…

…igital/wmn-design-system into hb/feat/form-elements-docs

src/wmnds/components/form-elements/label/_label.njk

@@ -1,11 +1,12 @@
 {% macro wmndsLabel(params) %}
 {# Set vars and defaults #}
-{% set for = params.for if params.for else "genericInput" %}
+
 {% set contentText = params.contentText if params.contentText else "Form label" %}
-{% set classes = " " + params.classes if params.classes %}
-{% set contentHTML = params.contentHTML if params.contentHTML else contentText %}
-{% set _label = contentHTML | safe if contentHTML else contentText %}
+{% set contentHTML = params.contentHTML if params.contentHTML else null %}
+{% set _labelContent = contentHTML | safe if contentHTML else contentText %} {# change content based on what user has input #}
+{% set classes = " " + params.classes if params.classes else null %}
+{% set for = params.for if params.for else "genericInput" %}
 
-<label class="wmnds-fe-label{{classes}}" for="{{for}}">{{ _label }}</label>
+<label class="wmnds-fe-label{{classes}}" for="{{for}}">{{ _labelContent }}</label>
 
 {% endmacro %}

src/wmnds/components/form-elements/textarea/_example.njk

@@ -0,0 +1,34 @@
+{% raw %}
+{% from "wmnds/components/form-elements/textarea/_textarea.njk" import wmndsTextarea %}
+
+{{
+   wmndsTextarea({
+      id: "example-textarea",
+      name: "example-textarea",
+      rows: "2",
+      error: false,
+      errorMessage: {
+         contentText: null,
+         contentHTML: "<span>Custom <em>error message</em></span>",
+         id: null,
+         classes: null
+      }
+      required: true,
+      classes: null,
+      label: {
+         contentText: "Textarea label",
+         contentHTML: "<span>Textarea label <em>updated</em></span>",
+         classes: "wmnds-m-t-20"
+      },
+      formGroup: {
+         classes: "wmnds-m-t-20"
+      },
+      attributes: {
+         disabled: false,
+         maxLength: "200",
+         placeholder: "Textarea placeholder...",
+         value: null
+      }
+    })
+}}
+{% endraw %}

src/wmnds/components/form-elements/textarea/_properties.njk.json

@@ -0,0 +1,122 @@
+{
+  "wmndsTextareaProps": [
+    {
+      "name": "id",
+      "type": "string",
+      "description": "<strong>Required.</strong> Must be unique. The id of the textarea."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "description": "<strong>Required.</strong> The name of the textarea, which is submitted with the form data."
+    },
+    {
+      "name": "rows",
+      "type": "string",
+      "description": "Optional number of textarea rows. Default is <code class='wmnds-website-inline-code'>3 rows</code>."
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "description": "If true, textarea is required/must be filled out. Defaults to <code class='wmnds-website-inline-code'>false</code>."
+    },
+    {
+      "name": "error",
+      "type": "boolean",
+      "description": "If true, an error will be displayed. Defaults to <code class='wmnds-website-inline-code'>false</code>."
+    },
+    {
+      "name": "errorMessage",
+      "type": "object",
+      "description": "Options for the error message component. See errorMessage.",
+      "arrayOptions": [
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Id attribute to add to the error message span tag."
+        },
+        {
+          "name": "contentText",
+          "type": "string",
+          "description": "<strong>Required.</strong> Text to use within the error message. If <code class='wmnds-website-inline-code'>contentHTML</code> is supplied, this is ignored."
+        },
+        {
+          "name": "contentHTML",
+          "type": "string",
+          "description": "<strong>Required.</strong> HTML to use within the error message"
+        },
+        {
+          "name": "classes",
+          "type": "string",
+          "description": "Classes to add to the error message span tag."
+        }
+      ]
+    },
+    {
+      "name": "classes",
+      "type": "string",
+      "description": "Classes to add to the textarea."
+    },
+    {
+      "name": "Label",
+      "type": "Object",
+      "description": "<strong>Required.</strong> Options for the label component. See label.",
+      "arrayOptions": [
+        {
+          "name": "contentText",
+          "type": "string",
+          "description": "<strong>Required.</strong> If `contentHTML` is set, this is not required. Text to use within the label. If `contentHTML` is provided, the `contentText`  argument will be ignored."
+        },
+        {
+          "name": "contentHTML",
+          "type": "string",
+          "description": "<strong>Required.</strong> If `contentText` is set, this is not required. HTML to use within the label. If `contentHTML` is provided, the `contentText` argument will be ignored."
+        },
+        {
+          "name": "classes",
+          "type": "string",
+          "description": "Classes to add to the label tag."
+        }
+      ]
+    },
+    {
+      "name": "formGroup",
+      "type": "Object",
+      "description": "Options for the form-group wrapper See formGroup below.",
+      "arrayOptions": [
+        {
+          "name": "classes",
+          "type": "string",
+          "description": "Classes to add to the form group (e.g. to show error state for the whole group)"
+        }
+      ]
+    },
+    {
+      "name": "attributes",
+      "type": "object",
+      "description": "Attribute to identify textarea purpose, for instance <code class='wmnds-website-inline-code'>postal-code</code> or <code class='wmnds-website-inline-code'>username</code>. See autofill for full list of attributes that can be used.",
+      "arrayOptions": [
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "description": "If true, textarea should be disabled. Defaults to <code class='wmnds-website-inline-code'>false</code>."
+        },
+        {
+          "name": "maxLength",
+          "type": "string",
+          "description": "The maxLength is the maximum number of characters allowed in the text area. It's an <code class='wmnds-website-inline-code'>optional</code> field."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "description": "Placeholder is a short hint that describes the expected value of a text area. It's an <code class='wmnds-website-inline-code'>optional</code> field."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Optional initial value of the textarea."
+        }
+      ]
+    }
+  ]
+}

src/wmnds/components/form-elements/textarea/_textarea.njk

@@ -2,18 +2,63 @@
 
 {# Imports #}
 {% from "wmnds/components/form-elements/label/_label.njk" import wmndsLabel %}
+{% from "wmnds/components/form-elements/error-message/_error-message.njk" import wmndsFeErrorMessage %}
 
 {# Params #}
 {% set id = params.id if params.id else "textarea" %}
+{% set name = params.name if params.name else id %}
+{% set rows = params.rows if params.rows else 3 %}
+{% set required = params.required if params.required else false %}
+{% set classes = " " + params.classes if params.classes %}
+{# Error Message Params #}
+{% set groupErrorClass = " wmnds-fe-group--error" if params.error %}
+{% set textareaErrorClass = " wmnds-fe-input--error" if params.error %}
+{% set errorContentText = params.errorMessage.contentText if params.errorMessage.contentText else "Please enter some text" %}
+{% set errorContentHTML = params.errorMessage.contentHTML if params.errorMessage.contentHTML else null %}
+{% set errorClasses = " " + params.errorMessage.classes if params.errorMessage.classes else null %}
+{% set errorId = params.errorMessage.id if params.errorMessage.id else null %}
+{# Params of label #}
+{% set labelContentText = params.label.contentText if params.label.contentText else "Form label" %}
+{% set labelContentHTML = params.label.contentHTML if params.label.contentHTML else null %}
+{% set labelClasses = params.label.classes if params.label.classes else null %}
+{# Params of formGroup #}
+{% set formGroupClasses = " " + params.formGroup.classes if params.formGroup.classes else null %}
+{# Params of Attributes #}
+{% set disabled = params.attributes.disabled if params.attributes.disabled else null %}
+{% set maxLength = params.attributes.maxLength if params.attributes.maxLength else null %}
+{% set placeholder = params.attributes.placeholder if params.attributes.placeholder else null %}
+{% set value = params.attributes.value if params.attributes.value else null %}
 
-<div class="wmnds-fe-group">
+
+<div class="wmnds-fe-group{{formGroupClasses}}{{groupErrorClass}}">
   {{
     wmndsLabel({
-      contentText: 'Textarea label',
+      contentText: labelContentText,
+      contentHTML: labelContentHTML,
+      classes: labelClasses,
       for: id
-    }) | trim
+    })
   }}
-  <textarea  class="wmnds-fe-textarea" id="{{id}}" name="{{id}}" rows="3"></textarea>
+  {% if params.error %}
+    {{
+      wmndsFeErrorMessage({
+          contentText: errorContentText,
+          contentHTML: errorContentHTML,
+          classes: errorClasses,
+          id: errorId
+      })
+    }}
+  {% endif %}
+  <textarea 
+    class="wmnds-fe-textarea{{classes}}{{textareaErrorClass}}" 
+    id="{{id}}" 
+    name="{{name}}" 
+    rows="{{rows}}"
+    {% if disabled %} disabled {% endif %}
+    {% if maxLength %} maxLength="{{maxLength}}" {% endif %} 
+    {% if placeholder %} placeholder="{{placeholder}}" {% endif %} 
+    {% if required %} required {% endif %}
+  >{% if value %}{{value}}{% endif %}</textarea>
 </div>
 
 {% endmacro %}

src/www/data.njk.json

@@ -92,6 +92,9 @@
         {
           "name": "Table"
         },
+        {
+          "name": "Textarea"
+        },
         {
           "name": "Text Input"
         },

src/www/pages/components/textarea/index.njk.md

@@ -0,0 +1,112 @@
+{% extends "www/_layouts/layout-left-pane.njk" %}
+{% set pageTitle = "Textarea" %}
+{% from "www/_partials/component-example/component-example.njk" import compExample %}
+{% from "wmnds/components/form-elements/textarea/_textarea.njk" import wmndsTextarea %}
+
+{% block content %}
+
+{% markdown %}
+
+## About
+
+### What does it do?
+
+- Allows users to enter more than one line of text.
+- Allows users to write whatever they like, also called free text.
+
+### When to use it?
+
+- When the user needs to enter lots of text. For example, a paragraph.
+
+### When not to use it?
+
+- When the user needs to enter one line of text. Use the input component instead.
+- Use fixed-width inputs for content that has a known length, e.g. postcode.
+- When there are limited options. Use a different form element that limits the options.
+
+{% endmarkdown %}
+
+{{
+    compExample(
+      [wmndsTextarea({
+          id: "example-textarea",
+          name: "example-textarea",
+          rows: "2",
+          required: true,
+          classes: null,
+          error: false,
+          errorMessage: {
+            contentText: "Input custom error message"
+          },
+          label: {
+            contentText: "Textarea label",
+            classes: "wmnds-m-t-20"
+          },
+          formGroup: {
+            classes: "wmnds-m-t-20"
+          },
+          attributes: {
+            disabled: false,
+            maxLength: "200",
+            placeholder: "Textarea placeholder...",
+            value: null
+          }
+        }
+      )],
+      {
+        componentPath: "wmnds/components/form-elements/textarea/",
+        njk: true,
+        njkProps: wmndsTextareaProps,
+        js: false,
+        iframe: false
+      }
+    )
+}}
+{# End Textarea #}
+
+{% markdown %}
+
+### Showing error
+
+{% endmarkdown %}
+
+{{
+    compExample(
+      [wmndsTextarea(
+        {
+          id: "example-textarea",
+          name: "example-textarea",
+          rows: "2",
+          required: true,
+          classes: null,
+          error: true,
+          errorMessage: {
+            contentText: "Textarea custom error message"
+          },
+          label: {
+            contentText: "Textarea label",
+            classes: "wmnds-m-t-20"
+          },
+          formGroup: {
+            classes: "wmnds-m-t-20"
+          },
+          attributes: {
+            disabled: false,
+            maxLength: "200",
+            placeholder: "Textarea placeholder...",
+            value: null
+          }
+        }
+      )],
+      {
+        componentPath: "wmnds/components/form-elements/textarea/",
+        njk: true,
+        njkProps: wmndsTextareaProps,
+        js: false,
+        iframe: false
+      }
+    )
+}}
+{# End Textarea #}
+
+{% endblock %}