From 3122e64b575b8ffbc930e64a9009174034c7f433 Mon Sep 17 00:00:00 2001
From: Catia Costa <34938764+catiarodriguescosta@users.noreply.github.com>
Date: Tue, 12 Jan 2021 16:20:27 +0000
Subject: [PATCH] feat: form elements - textarea documentation (#581)

* Transform textarea as stand alone component (was inside form elements before). Update params. Add documentation and nunjunks example.

* Update textarea inspired on gov website.

* Basic update to error message.

* Basic params update to label component.

* Add errorMessage properties and add error classes to textarea.

* Update textarea example.

* Update textarea params/properties. Add showing error example.

* Move textarea back to form-elements folder.

* Litle text amend & default error message for textarea.
---
 .../components/form-elements/label/_label.njk |  11 +-
 .../form-elements/textarea/_example.njk       |  34 +++++
 .../textarea/_properties.njk.json             | 122 ++++++++++++++++++
 .../form-elements/textarea/_textarea.njk      |  53 +++++++-
 src/www/data.njk.json                         |   3 +
 .../pages/components/textarea/index.njk.md    | 112 ++++++++++++++++
 6 files changed, 326 insertions(+), 9 deletions(-)
 create mode 100644 src/wmnds/components/form-elements/textarea/_example.njk
 create mode 100644 src/wmnds/components/form-elements/textarea/_properties.njk.json
 create mode 100644 src/www/pages/components/textarea/index.njk.md

diff --git a/src/wmnds/components/form-elements/label/_label.njk b/src/wmnds/components/form-elements/label/_label.njk
index 2a437a22c..95d8d14e2 100644
--- a/src/wmnds/components/form-elements/label/_label.njk
+++ b/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 %}
\ No newline at end of file
diff --git a/src/wmnds/components/form-elements/textarea/_example.njk b/src/wmnds/components/form-elements/textarea/_example.njk
new file mode 100644
index 000000000..ee5e5f263
--- /dev/null
+++ b/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 %}
diff --git a/src/wmnds/components/form-elements/textarea/_properties.njk.json b/src/wmnds/components/form-elements/textarea/_properties.njk.json
new file mode 100644
index 000000000..6d83559be
--- /dev/null
+++ b/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."
+        }
+      ]
+    }
+  ]
+}
diff --git a/src/wmnds/components/form-elements/textarea/_textarea.njk b/src/wmnds/components/form-elements/textarea/_textarea.njk
index 48e57c5a5..c2c55c071 100644
--- a/src/wmnds/components/form-elements/textarea/_textarea.njk
+++ b/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 %}
\ No newline at end of file
diff --git a/src/www/data.njk.json b/src/www/data.njk.json
index 12675a540..794f69989 100644
--- a/src/www/data.njk.json
+++ b/src/www/data.njk.json
@@ -95,6 +95,9 @@
         {
           "name": "Table"
         },
+        {
+          "name": "Textarea"
+        },
         {
           "name": "Text Input"
         },
diff --git a/src/www/pages/components/textarea/index.njk.md b/src/www/pages/components/textarea/index.njk.md
new file mode 100644
index 000000000..6614153a4
--- /dev/null
+++ b/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 %}