From 1fbe5b5957bde3f48000bbef31176637501afdf8 Mon Sep 17 00:00:00 2001
From: Gil Greenberg <ggreenberg@somethingdigital.com>
Date: Thu, 16 Aug 2018 16:51:29 -0400
Subject: [PATCH] improvement: Add Hint Option to all Widgets (#1429)

* Add hint to example admin config

* Add hint and hint position boolean above/below widget

* Style hint for both above and below widget

* Add hint and hint_above options to docs

* Remove hint above and make hint plaintext
---
 dev-test/config.yml                               |  8 ++++----
 .../Editor/EditorControlPane/EditorControl.js     | 15 +++++++++++++++
 .../Editor/EditorControlPane/EditorControlPane.js |  4 ++--
 website/content/docs/widgets/index.md             |  1 +
 4 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/dev-test/config.yml b/dev-test/config.yml
index 1e077c60..fc0a5ae5 100644
--- a/dev-test/config.yml
+++ b/dev-test/config.yml
@@ -20,7 +20,7 @@ collections: # A list of collections the CMS should be able to edit
       - {label: "Title", name: "title", widget: "string", tagname: "h1"}
       - {label: "Publish Date", name: "date", widget: "datetime", format: "YYYY-MM-DD hh:mma"}
       - {label: "Cover Image", name: "image", widget: "image", required: false, tagname: ""}
-      - {label: "Body", name: "body", widget: "markdown"}
+      - {label: "Body", name: "body", widget: "markdown", hint: "Main content goes here."}
     meta:
       - {label: "SEO Description", name: "description", widget: "text"}
 
@@ -62,7 +62,7 @@ collections: # A list of collections the CMS should be able to edit
             label_singular: "Author"
             widget: list
             fields:
-              - {label: "Name", name: "name", widget: "string"}
+              - {label: "Name", name: "name", widget: "string", hint: "First and Last"}
               - {label: "Description", name: "description", widget: "markdown"}
 
   - name: "kitchenSink" # all the things in one entry, for documentation and quick testing
@@ -79,8 +79,8 @@ collections: # A list of collections the CMS should be able to edit
         valueField: "title"
       - {label: "Title", name: "title", widget: "string"}
       - {label: "Boolean", name: "boolean", widget: "boolean", default: true}
-      - {label: "Text", name: "text", widget: "text"}
-      - {label: "Number", name: "number", widget: "number"}
+      - {label: "Text", name: "text", widget: "text", hint: "Plain text, not markdown"}
+      - {label: "Number", name: "number", widget: "number", hint: "To infinity and beyond!"}
       - {label: "Markdown", name: "markdown", widget: "markdown"}
       - {label: "Datetime", name: "datetime", widget: "datetime"}
       - {label: "Date", name: "date", widget: "date"}
diff --git a/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControl.js b/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControl.js
index f9d99a92..db5d82cc 100644
--- a/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControl.js
+++ b/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControl.js
@@ -103,6 +103,15 @@ const ControlErrorsList = styled.ul`
   top: 20px;
 `;
 
+export const ControlHint = styled.p`
+  margin-bottom: 0;
+  padding: 3px 0;
+  font-size: 12px;
+  color: ${({ active, error }) =>
+    error ? colors.errorText : active ? colors.active : colors.controlLabel};
+  transition: color ${transitions.main};
+`;
+
 class EditorControl extends React.Component {
   state = {
     activeLabel: false,
@@ -130,6 +139,7 @@ class EditorControl extends React.Component {
     const widgetName = field.get('widget');
     const widget = resolveWidget(widgetName);
     const fieldName = field.get('name');
+    const fieldHint = field.get('hint');
     const uniqueFieldId = uniqueId();
     const metadata = fieldsMetaData && fieldsMetaData.get(fieldName);
     const errors = fieldsErrors && fieldsErrors.get(fieldName);
@@ -189,6 +199,11 @@ class EditorControl extends React.Component {
           clearSearch={clearSearch}
           isFetching={isFetching}
         />
+        {fieldHint && (
+          <ControlHint active={this.state.styleActive} error={!!errors}>
+            {fieldHint}
+          </ControlHint>
+        )}
       </ControlContainer>
     );
   }
diff --git a/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControlPane.js b/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControlPane.js
index 4a4da769..3156903a 100644
--- a/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControlPane.js
+++ b/packages/netlify-cms-core/src/components/Editor/EditorControlPane/EditorControlPane.js
@@ -2,14 +2,14 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import ImmutablePropTypes from 'react-immutable-proptypes';
 import styled from 'react-emotion';
-import EditorControl from './EditorControl';
+import EditorControl, { ControlHint } from './EditorControl';
 
 const ControlPaneContainer = styled.div`
   max-width: 800px;
   margin: 0 auto;
   padding-bottom: 16px;
 
-  p {
+  p:not(${ControlHint}) {
     font-size: 16px;
   }
 `;
diff --git a/website/content/docs/widgets/index.md b/website/content/docs/widgets/index.md
index 61d12b38..f40b1641 100644
--- a/website/content/docs/widgets/index.md
+++ b/website/content/docs/widgets/index.md
@@ -16,6 +16,7 @@ To see working examples of all of the built-in widgets, try making a 'Kitchen Si
 The following options are available on all fields:
 
 - `required`: specify as `false` to make a field optional; defaults to `true`
+- `hint`: optionally add helper text directly below a widget. Useful for including instructions.
 - `pattern`: add field validation by specifying a list with a [regex pattern](https://regexr.com/) and an error message; more extensive validation can be achieved with [custom widgets](https://www.netlifycms.org/docs/custom-widgets/#advanced-field-validation)
   - **Example:**
         ```yaml