@springernature/global-forms - npm Package Compare versions

Comparing version 5.0.0-rc.7 to 5.0.0-rc.8

demo/context.json

@@ -17,4 +17,5 @@ {
 		},
-		"fieldsets": [
+		"fields": [
 			{
+				"template": "globalFormFieldset",
 				"legend": "<h2>Text inputs</h2>",
@@ -66,3 +67,5 @@ "fields": [
 				]
-			},
+			}
+		],
+		"fieldsets": [
 			{
@@ -156,2 +159,61 @@ "legend": "<h2>Selects</h2>",
 			{
+				"legend": "<h2>Pictographic Radios</h2>",
+				"fields": [
+					{
+						"template": "globalFormRadios",
+						"label": "Rating",
+						"groupDescription": "A scale of 5 feelings conveyed using images that range from terrible to great. The feelings represent how you feel about this page.",
+						"id": "radios-rating",
+						"name": "radios-rating",
+						"pictographic": true,
+						"boxed": true,
+						"inputs": [
+							{
+								"label": "Terrible",
+								"value": "Terrible",
+								"id": "radio-terrible",
+								"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\"> <defs> <clipPath id=\"crya\"> <path d=\"M24 0v24H0V0h24Z\"/> </clipPath> </defs> <g clip-path=\"url(#crya)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M6.5 20.4A10 10 0 1 0 2 12\"/> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M9 17c1-2.7 5-2.7 6 0\"/> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M2.7 18.3a2 2 0 0 1-.7-2.8c.4-.6 1.5-1.1 3.2-1.5.6 1.7.7 2.9.3 3.5a2 2 0 0 1-2.8.8ZM9 10l-2 1M17 11l-2-1\"/> </g> </svg>",
+								"showLabel": true,
+								"imageDescription": "An image of a cartoon face that is crying."
+							},
+							{
+								"label": "Bad",
+								"value": "Bad",
+								"id": "radio-bad",
+								"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\"> <defs> <clipPath id=\"frowna\"> <path d=\"M24 0v24H0V0h24Z\"/> </clipPath> <clipPath id=\"frownb\"> <path d=\"M1 0c.6 0 1 .4 1 1v2a1 1 0 1 1-2 0V1c0-.6.4-1 1-1Z\"/> </clipPath> </defs> <g clip-path=\"url(#frowna)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Z\"/> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M9 17c1-2.7 5-2.7 6 0\"/> <g clip-path=\"url(#frownb)\" transform=\"translate(8 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> <g clip-path=\"url(#frownb)\" transform=\"translate(14 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> </g> </svg>",
+								"showLabel":  false,
+								"imageDescription": "An image of a cartoon face with a frown."
+
+							},
+							{
+								"label": "OK",
+								"value": "OK",
+								"id": "radio-ok",
+								"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\"> <defs> <clipPath id=\"neutrala\"> <path d=\"M24 0v24H0V0h24Z\"/> </clipPath> <clipPath id=\"neutralb\"> <path d=\"M1 0c.6 0 1 .4 1 1v2a1 1 0 1 1-2 0V1c0-.6.4-1 1-1Z\"/> </clipPath> </defs> <g clip-path=\"url(#neutrala)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Z\"/> <g clip-path=\"url(#neutralb)\" transform=\"translate(8 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> <g clip-path=\"url(#neutralb)\" transform=\"translate(14 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M9 16h6\"/> </g> </svg>",
+								"showLabel":  false,
+								"imageDescription": "An image of a cartoon face with a neutral expression."
+
+							},
+							{
+								"label": "Good",
+								"value": "Good",
+								"id": "radio-good",
+								"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\"  aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\"> <defs> <clipPath id=\"smilea\"> <path d=\"M24 0v24H0V0h24Z\"/> </clipPath> <clipPath id=\"smileb\"> <path d=\"M1 0c.6 0 1 .4 1 1v2a1 1 0 1 1-2 0V1c0-.6.4-1 1-1Z\"/> </clipPath> </defs> <g clip-path=\"url(#smilea)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Z\"/> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M9 15c1 2.7 5 2.7 6 0\"/> <g clip-path=\"url(#smileb)\" transform=\"translate(8 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> <g clip-path=\"url(#smileb)\" transform=\"translate(14 8)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"2\" stroke-linejoin=\"round\" d=\"M0 0h2v4H0V0z\"/> </g> </g> </svg>",
+								"showLabel":  false,
+								"imageDescription": "An image of a cartoon face with a smile."
+
+							},
+							{
+								"label": "Great",
+								"value": "Great",
+								"id": "radio-great",
+								"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\"> <defs> <clipPath id=\"grina\"> <path d=\"M24 0v24H0V0h24Z\"/> </clipPath> </defs> <g clip-path=\"url(#grina)\"> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Z\"/> <path stroke-linecap=\"round\" stroke-miterlimit=\"10\" stroke-width=\"1.8\" stroke-linejoin=\"round\" d=\"M17.5 10v-.5a1.7 1.7 0 0 0-3.5 0v.5M10 10v-.5a1.7 1.7 0 0 0-3.5 0v.5M8 14c.5 5 7.5 5 8 0H8Z\"/> </g> </svg>",
+								"showLabel":  true,
+								"imageDescription": "An image of a cartoon face with an open mouth grin."
+							}
+						]
+					}
+				]
+			},
+			{
 				"legend": "<h2>Textareas</h2>",
@@ -235,2 +297,3 @@ "fields": [
 	"dynamicPartials": {
+		"globalFormField": "./toolkits/global/packages/global-forms/view/globalFormField.hbs",
 		"globalFormFieldset": "./toolkits/global/packages/global-forms/view/globalFormFieldset.hbs",
@@ -237,0 +300,0 @@ "globalFormLabel": "./toolkits/global/packages/global-forms/view/globalFormLabel.hbs",

HISTORY.md

 # History
 
+## 5.0.0-rc.8 (2022-09-16)
+    * BREAKING:
+        * Creation of field partial (`globalFormField.hbs)` to allow for iterating over fields without fieldsets
+        * Fields with no labels no longer hidden; `hidden: true` supported instead, for any field
+    * Adds support for pictographic radio elements
+    * Bumps Brand Context to v28.0.1
+
 ## 5.0.0-rc.7 (2022-09-09)
@@ -4,0 +11,0 @@ * Adds support for pattern attribute

package.json

 {
 	"name": "@springernature/global-forms",
-	"version": "5.0.0-rc.7",
+	"version": "5.0.0-rc.8",
 	"license": "MIT",
@@ -11,3 +11,3 @@ "description": "form component",
   "author": "Heydon Pickering",
-  "brandContext": "^26.0.0"
+  "brandContext": "^28.0.1"
 }

README.md

@@ -25,59 +25,33 @@ # Global Forms
 
-Then you will need to register the handlebars partials in the `/view` folder. 
+Then you will need to register the handlebars partials in the `/view` folder. There are two options for rendering form fields: 
 
-There are two options for rendering form fields: 
-
 1. Compile fields independently, using their respective templates from the `view/fields` folder.
-2. Organise multiple related fields into fieldsets using the data structure like that shown in `demo/context.json`. For example, a group of fields used to let someone enter their address. In this case, you’ll have to iterate over a `fieldsets` array something like this:
+2. Organize your data into arrays of fieldsets and fields and loop over these arrays, assigning the `globalFormFieldset` and `globalFormField` partials respectively.
 
+Here is an example base template implementation:
+
 ```html
-<form action="some/url">
-    {{#with myFormData}}
-		{{#with errorSummary}}
-			{{> errorSummary }}
-		{{/with}}
-		{{#each fieldsets}}
-			{{> fieldset }}
-		{{/each}}
-    {{/with}}
+<form id="my-form" action="/something">
+    {{#each myFields}}
+        {{> globalFormField}}
+    {{/each}}
 </form>
 ```
 
-### Fieldsets
+For this example, you might have two simple inputs for a name and password:
 
-Fieldsets are used to group fields itemised under their `fields` property. If you do not want to include a (visible; screen reader identifiable) fieldset element or legend, simply omit the `legend` property. The following example shows a simple form body with a single, unlabelled fieldset containing two text inputs:
-
 ```json
-"fieldsets": {
+"myFields": {
     [
         {
-            "fields": [
-                {
-                    "template": "globalFormText",
-                    "label": "Your name",
-                    "id": "your-name",
-                    "name": "your-name"
-                },
-                {
-                    "template": "globalFormText",
-                    "label": "Your email",
-                    "id": "your-email",
-                    "name": "your-email"
-                }
-            ]
-        }
-    ]
-}
-```
-
-If you do wish to include a legend, you can use HTML to style it and add semantic meaning. In most cases, legends should be headings, with the heading level determined by the page structure.
-
-```json
-"fieldsets": {
-    [
+            "template": "globalFormText",
+            "label": "Your name",
+            "id": "your-name",
+            "name": "your-name",
+        },
         {
-            "legend": "<h2>My level 2 legend</h2>",
-            "fields": [
-                ...
-            ]
+            "template": "globalFormPassword",
+            "name": "password",
+            "label": "Your password",
+            "id": "password"
         }
@@ -90,3 +64,3 @@ ]
 
-The `template` property sets the type of field - for example, `"template": "globalFormText"` renders a text input field if that is what you have registered the **view/fields/globalFormText.hbs** template as. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.
+The `template` property sets the type of field - for example, `"template": "globalFormText"` renders a text input field if that is what you have registered the **view/fields/globalFormText.hbs** template as. Aim to make the `template`, `id`, and `name` properties mandatory parts of your data schema.
 
@@ -147,3 +121,3 @@ This component supports a wide range of standard form field attributes. For example, to include a `readonly` attribute on your text input, you can include a property of the same name on the data:
 
-You can summarise errors using a top level `errorSummary` property adjacent to the `fieldsets` property. Each error in the errors array must point to the `id` of the input it relates to and repeat its `error` message:
+You can summarise errors using a top level `errorSummary` property. Each error in the errors array must point to the `id` of the input it relates to and repeat its `error` message:
 
@@ -169,2 +143,4 @@ ```json
 
+#### Select fields
+
 `Select` fields (using the `<select>` element) define the user’s options with an `options` property, which must be an array. The `selected` property is a Boolean:
@@ -186,2 +162,4 @@
 
+#### Radio groups
+
 Radios define choices with an `inputs` array:
@@ -212,2 +190,66 @@
 
+Pictographic radios are also supported and can be enabled by including the property `pictographic: true`:
+
+```json
+{
+    "legend": "Pictographic Radios",
+    "fields": [
+        {
+            "template": "globalFormRadios",
+            "label": "Rating",
+            "description": "A scale of 5 feelings conveyed using images that range from terrible to great. The feelings represent how you feel about this page.",
+            "id": "radios-rating",
+            "name": "radios-rating",
+            "pictographic": true,
+            "boxed": true,
+            "inputs": [...]
+        }
+    ]
+}
+```
+There are two other properties in the above example that are used to configure pictographic radios: `groupDescription` and `boxed`.
+
+It is strongly recommended that the `groupDescription` property is set when defining a group of pictographic radios to ensure users of assistive technologies are provided with sufficient information to understand the group of radio elements.
+
+The `boxed` property allows for `border` and `padding` to be applied to the pictographic radio's SVG elements. When this setting is enabled the CSS classname `c-forms__label--boxed-icon` is applied to the component's HTML to facilitate this.
+
+As with ordinary radio elements, data for each pictographic radio element is defined in the `inputs` array. In this example, the path data is removed for brevity.
+
+```json
+"inputs": [
+    {
+        "label": "Bad",
+        "value": "Bad",
+        "id": "radio-bad",
+        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\">...</svg>",
+        "showLabel":  false,
+        "imageDescription": "An image of a cartoon face with a frown."
+    },
+    {
+        "label": "OK",
+        "value": "OK",
+        "id": "radio-ok",
+        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"transparent\" stroke=\"currentColor\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 24 24\">...</svg>",
+        "showLabel":  false,
+        "imageDescription": "An image of a cartoon face with a neutral expression."
+    }
+]
+```
+
+However, there are properties in the above example that are unique to pictographic radios: `svg`, `showLabel`, and `imageDescription`.
+
+The images used for pictographic radios must be defined as inline SVG elements using the `svg` property. This property is mandatory and must contain a string defining the inline SVG code. Please note that special characters within the string such as double quotes must be escaped.
+
+The `showLabel` property allows for the `<label>` text to be visually hidden. If you choose to enable this setting for a radio input label please ensure it does not negatively impact the user experience, particularly accessibility.
+
+It is strongly recommended that the `imageDescription` property is set when defining a pictographic radio to ensure users of assistive technologies are provided with sufficient information to understand the meaning of the image that has been used.
+
+The width and height of each SVG can be overridden using the CSS variable `--forms--pictographic-radio-icon-size`. This can be applied to the SVG html in the `style` attribute as follows:
+
+```json
+"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"--forms--pictographic-radio-icon-size: 2rem\" focusable=\"false\" aria-hidden=\"true\" viewBox=\"0 0 24 24\">...</svg>"
+```
+
+#### Checkboxes
+
 Unlike radios, which are always used in sets of two or more, you can have a single checkbox field. To give users a set of checkbox choices, organise the checkboxes into a `fieldset`:
@@ -235,5 +277,17 @@
 
+### Hidden fields
 
-#### Supplementary fields
+You can hide any field from visibility (also from screen reader software and keyboard interaction) using `hidden: true`. If you want to use a field of `type="hidden"`, you need to use `template: globalFormHidden`. It is recommended you also apply `hidden: true` to such fields because it will remove the inter-field margin. In the following example, note the `label` is omitted since hidden fields are not user facing.
 
+```json
+ {
+    "template": "globalFormHidden",
+    "id": "hidden-field",
+    "name": "hidden-field",
+    "hidden": true,
+}
+```
+
+### Supplementary fields
+
 You might want to show users an additional field when they select a particular radio or checkbox. For example, revealing a text input field for them to give more specific information about the option they’ve selected.
@@ -312,1 +366,69 @@
 This builds a standard `datalist` field, with `option`s, and associates it with the input. If a `datalist` already exists in the markup, provide just the `id` and forego the `option` property. If you want to use a custom-built autocomplete solution using JavaScript, omit the `datalist` property from the field altogether.
+
+### Fieldsets
+
+Fieldsets are used to group fields itemised under their `fields` property, with a legend to label the fieldset itself. There are two ways to add fieldsets to your form:
+
+1. Create a field with the `template` value of `globalFormFieldset` and an array of fields using the `fields` property.
+2. Create an array of `fieldsets` and loop over them, assigning the `globalFormFieldset` partial.
+
+#### (1) The fieldset field
+
+```json
+{
+    "template": "globalFormFieldset",
+    "legend": "<h1>Login</h1>",
+    "fields": [
+        ...
+    ]
+```
+
+#### (2) A fieldset array
+
+In this case, each fieldset is an object:
+
+```json
+"myFieldsets": [
+    {
+        "legend": "<h2>One fieldset</h2>",
+        "fields": [
+            ...
+        ]
+    },
+    {
+        "legend": "<h2>Another, different fieldset</h2>",
+        "fields": [
+            ...
+        ]
+    }    
+]
+```
+
+And the accompanying template would include this:
+
+```html
+{{#each myFieldsets}}
+    {{> globalFormFieldset}}
+{{/each}}
+```
+
+A fieldset can include one or more nested fieldsets. If you are including headings in your fieldsets, be careful to use a heading level that reflects the nesting level. For example, if a fieldset’s legend uses `<h2>`, any child fieldset within it should use `<h3>` or no heading level at all.
+
+#### Legends
+
+You can use HTML to style the legend and add semantic meaning. In most cases, legends should be headings, with the heading level determined by the page structure.
+
+```json
+"fieldsets": {
+    [
+        {
+            "legend": "<h2>My level 2 legend</h2>",
+            "fields": [
+                ...
+            ]
+        }
+    ]
+}
+```
+
+For accessibility, do not use a fieldset without an accompanying legend. If a legend is not appropriate, neither is a fieldset; just use fields without a fieldset parent.

No alert changes

Improved metrics

Total package byte prevSize

108857

increased by30%

Number of package files

31

increased by3.33%

Lines of code

324

increased by29.08%

Number of lines in readme file

427

increased by40%

No dependency changes