feat: form elements - radios documentation

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

@@ -0,0 +1,55 @@
+{% raw %}
+{% from "wmnds/components/form-elements/radios/_radios.njk" import wmndsRadios %}
+
+{{
+  wmndsRadios({
+    items: [
+      {
+          id: null,
+          checked: false,
+          titleText: null,
+          contentText: "Option 1",
+          contentHTML: null,
+          value: "option1",
+          disabled: false
+      },
+      {
+          id: null,
+          checked: true,
+          titleText: null,
+          contentText: "Option 2",
+          contentHTML: null,
+          value: "option2",
+          disabled: false
+      },
+      {
+          id: null,
+          checked: false,
+          titleText: null,
+          contentText: "Option 3",
+          contentHTML: null,
+          value: "option3",
+          disabled: false
+      }
+    ],
+    question: "How would you...?",
+    idPrefix: "radios",
+    name: "radios-example",
+    classes: null,
+    inline: false,
+    hint: {
+      id: null,
+      classes: null,
+      contentText: "Select one option",
+      contentHTML: null
+    },
+      error: false,
+      errorMessage: {
+        contentText: "Please select an option",
+        contentHTML: null,
+        classes: null,
+        id: null
+      }
+  })
+}}
+{% endraw %}

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

@@ -0,0 +1,115 @@
+{
+  "wmndsRadiosProps": [
+    {
+      "name": "items",
+      "type": "array",
+      "description": "<strong>Required.</strong> Array of radio items objects. See <code class='wmnds-website-inline-code'>items</code> below.",
+      "arrayOptions": [
+        {
+          "name": "contentText",
+          "type": "string",
+          "description": "<strong>Required.</strong> If <code class='wmnds-website-inline-code'>contentHTML</code> is set, this is not required. Text to use within each radio item label. If <code class='wmnds-website-inline-code'>contentHTML</code> is provided, the <code class='wmnds-website-inline-code'>contentText</code> argument will be ignored."
+        },
+        {
+          "name": "contentHTML",
+          "type": "string",
+          "description": "<strong>Required.</strong> If <code class='wmnds-website-inline-code'>contentText</code> is set, this is not required. HTML to use within each radio item label. If <code class='wmnds-website-inline-code'>contentHTML</code> is provided, the <code class='wmnds-website-inline-code'>contentText</code> argument will be ignored."
+        },
+        {
+          "name": "checked",
+          "type": "boolean",
+          "description": "If true, radio will be checked."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Specific name for the radio item. If omitted, then component global name string will be applied."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "description": "If true, radio will be disabled."
+        }
+      ]
+    },
+    {
+      "name": "question",
+      "type": "string",
+      "description": "Text for the question component relating to the radios."
+    },
+    {
+      "name": "hint",
+      "type": "object",
+      "description": "Options for the hint component (e.g. text). See <code class='wmnds-website-inline-code'>hint</code> options below.",
+      "arrayOptions": [
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Optional id attribute to add to the hint span tag."
+        },
+        {
+          "name": "contentText",
+          "type": "string",
+          "description": "<strong>Required.</strong> If <code class='wmnds-website-inline-code'>contentHTML</code> is set, this is not required. Text to use within the hint. If <code class='wmnds-website-inline-code'>contentHTML</code> is provided, the <code class='wmnds-website-inline-code'>contentText</code> argument will be ignored."
+        },
+        {
+          "name": "contentHTML",
+          "type": "string",
+          "description": "<strong>Required.</strong> If <code class='wmnds-website-inline-code'>contentText</code> is set, this is not required. HTML to use within the hint. If <code class='wmnds-website-inline-code'>contentHTML</code> is provided, the <code class='wmnds-website-inline-code'>contentText</code> argument will be ignored."
+        },
+        {
+          "name": "classes",
+          "type": "string",
+          "description": "Classes to add to the hint span tag."
+        }
+      ]
+    },
+    {
+      "name": "idPrefix",
+      "type": "string",
+      "description": "String to prefix id for each radio item if no id is specified on each item. If not passed, fall back to using the name option instead."
+    },
+    {
+      "name": "inline",
+      "type": "boolean",
+      "description": "Determines whether to the display the radios horizontally or vertically."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "description": "<strong>Required.</strong> Name attribute for all radio items."
+    },
+    {
+      "name": "classes",
+      "type": "string",
+      "description": "Classes to add to the radios container."
+    },
+    {
+      "name": "error",
+      "type": "boolean",
+      "description": "If true, errorMessage will show. Defaults to <code class='wmnds-website-inline-code'>false</code>."
+    },
+    {
+      "name": "errorMessage",
+      "type": "object",
+      "description": "Options for the error message component. See <code class='wmnds-website-inline-code'>errorMessage</code> options below.",
+      "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"
+        }
+      ]
+    }
+  ]
+}

src/wmnds/components/form-elements/radios/_radios.njk

@@ -1,35 +1,86 @@
 {% macro wmndsRadios(params) %}
 
-{# Set vars #}
-{% set class = ' wmnds-fe-radios--inline' if params.inline %}
-{% set text = params.text if params.text %}
 
 {# Imports #}
 {% from "wmnds/components/form-elements/label/_label.njk" import wmndsLabel %}
 {% from "wmnds/components/icon/_icon.njk" import wmndsIcon %}
 {% from "wmnds/components/form-elements/question/_question.njk" import wmndsQuestion %}
+{% from "wmnds/components/form-elements/error-message/_error-message.njk" import wmndsFeErrorMessage %}
 
-<div class="wmnds-fe-group">
+{# Set vars #}
+{% set class = ' wmnds-fe-radios--inline' if params.inline %}
+{% set hasQuestion = false if params.question === "" else true %}
+{% set question = params.question if params.question %}
+{% set items = params.items if params.items %}
+{% set groupClass = " " + params.classes if params.classes %}
+{% set name = params.name if params.name else "checkbox-example" %}
+{% set hintContentText = params.hint.contentText if params.hint.contentText else "Select all options that apply" %}
+{% set hintContentHTML = params.hint.contentHTML if params.hint.contentHTML else null %}
+{% set _hintContent = hintContentHTML | safe if hintContentHTML else hintContentText %} {# change content based on what user has input #}
+{% set hasDescription = false if _hintContent === "" else true %}
+{% set idPrefix = params.idPrefix if params.idPrefix else name %}
+{% set hintClass = " " + params.hint.classes if params.hint.classes %}
+{# Error Message Params #}
+{% set groupErrorClass = " wmnds-fe-group--error" if params.error %}
+{% set errorContentText = params.errorMessage.contentText if params.errorMessage.contentText else "Please select an option" %}
+{% 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 %}
+
+<div class="wmnds-fe-group{{groupErrorClass}}">
   <fieldset class="wmnds-fe-fieldset">
     <legend class="wmnds-fe-fieldset__legend">
-      {{ wmndsQuestion({
-          text: text
-      }) | indent(6) | trim }}
+    {%- if hasQuestion %}
+    {{ 
+      wmndsQuestion({
+        text: question
+      })
+    }}
+    {% endif -%}
     </legend>
     <div class="wmnds-fe-radios{{class}}">
-      <span class="wmnds-fe-radios__desc">
-        Select one option
+      {% if params.error -%}
+        {{
+          wmndsFeErrorMessage(
+            {
+              contentText: errorContentText,
+              contentHTML: errorContentHTML,
+              classes: errorClasses,
+              id: errorId
+            }
+          )
+        }}
+      {% endif -%}
+      <span class="wmnds-fe-radios__desc{{hintClass}}" {% if params.hint.id %}id="{{params.hint.id}}"{% endif %}>
+        {{ _hintContent }}
       </span>
-      {%- for i in range(1,4) %}
+      {% if items %}
+      {%- for item in items %}
+      {# Set item vars #}
+      {% set isChecked = (' checked="checked"' | safe) if item.checked === true  else "" %}
+      {% set inputValue = item.value if item.value else "option" + loop.index | string %}
+      {% set inputId = item.id if item.id else idPrefix + "_" + inputValue %}
+      {% set isNotEditable = (' disabled="disabled"' | safe) if item.disabled === true else "" %}
+      {% set itemContentText = item.contentText if item.contentText else "Select one option" %}
+      {% set itemContentHTML = item.contentHTML if item.contentHTML else null %}
+      {% set _itemContent = itemContentHTML | safe if itemContentHTML else itemContentText %} {# change content based on what user has input #}
+      <label class="wmnds-fe-radios__container">
+        {{_itemContent}}
+        <input id="{{inputId}}" class="wmnds-fe-radios__input" value="{{inputValue}}"{{isChecked}} name="{{name}}" type="radio"{{isNotEditable}}/>
+        <span class="wmnds-fe-radios__checkmark"></span>
+      </label>
+      {% endfor %}
+      {% else %}
+      {% for i in range(1,4) %}
       {#- Set checked state on first item in loop #}
-      {%- set isChecked = (' checked="checked"' | safe) if i === 1 %}
+      {% set isChecked = (' checked="checked"' | safe) if i === 1 %}
       <label class="wmnds-fe-radios__container">
         Option {{i}}
-        <input class="wmnds-fe-radios__input" value="Option {{i}}"{{isChecked}} name="radio-example" type="radio"/>
-        <span class="wmnds-fe-radios__checkmark">
-        </span>
+        <input class="wmnds-fe-radios__input" value="Option {{i}}"{{isChecked}} name="{{name}}" type="radio"/>
+        <span class="wmnds-fe-radios__checkmark"></span>
       </label>
-      {%- endfor %}
+      {% endfor %}
+      {% endif %}
     </div>
   </fieldset>
 </div>

src/www/data.njk.json

@@ -80,6 +80,9 @@
         {
           "name": "Phase indicator"
         },
+        {
+          "name": "Radios"
+        },
         {
           "name": "Table"
         },

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

@@ -0,0 +1,85 @@
+{% extends "www/_layouts/layout-left-pane.njk" %}
+{% set pageTitle = "Radios" %}
+{% from "www/_partials/component-example/component-example.njk" import compExample %}
+
+{% block content %}
+
+{% markdown %}
+
+{# Radios #}
+
+## About
+
+### What does it do?
+
+- Allows users select one option from multiple options.
+
+### When to use it?
+
+- When user can select just one option from multiple options.
+
+### When not to use it?
+
+- When user may need to select more than one option.
+
+{% endmarkdown %}
+
+{% from "wmnds/components/form-elements/radios/_radios.njk" import wmndsRadios %}
+{{
+  compExample([
+    wmndsRadios()
+  ], {
+    componentPath: "wmnds/components/form-elements/radios/",
+    njk: true,
+    njkProps: wmndsRadiosProps,
+    js: false,
+    iframe: false
+  })
+}}
+
+{% markdown %}
+
+### Inline Radios
+
+{% endmarkdown %}
+
+{{
+  compExample([
+    wmndsRadios({
+      inline: true,
+      name: "inline-example"
+    })
+  ], {
+    componentPath: "wmnds/components/form-elements/radios/",
+    njk: true,
+    njkProps: wmndsRadiosProps,
+    js: false,
+    iframe: false
+  })
+}}
+{# End Radios #}
+
+{% markdown %}
+
+### Radio with error
+
+{% endmarkdown %}
+
+{{
+  compExample([
+    wmndsRadios({
+      inline: true,
+      name: "inline-example",
+      error: true
+    })
+  ], {
+    componentPath: "wmnds/components/form-elements/radios/",
+    njk: true,
+    njkProps: wmndsRadiosProps,
+    js: false,
+    iframe: false
+  })
+}}
+{# End Radios #}
+
+{% endblock %}