Global Forms #743

Heydon · 2022-05-05T10:55:32Z

Major reworking of global-forms following the formation of The Commitee For HTML Forms™️ (@alexkilgour, @Heydon, @sturobson, @axemonkey, @sky-jack). Design is informed by @foxintherain's work: https://www.sketch.com/s/c77d316e-76e5-403e-95b8-93021fc6c95e/p/0EB75A8C-3CC3-40C8-A48E-AE685CB267BC. Note that the button styles have not been updated to reflect the Sketch file since this is a separate concern with a broader scope.

This is an RC (release candidate) release.

From the HISTORY.md file:

## 5.0.0-rc.1 (2022-06-27)
    * BREAKING:
        * Form fields now available as a suite of templates/partials
        * Major changes to styling and styling API
        * Design tokens support

Includes comprehensive documentation.

alexkilgour · 2022-07-01T07:40:01Z

toolkits/global/packages/global-forms/scss/00-tokens/_default.tokens.scss

@@ -0,0 +1,34 @@
+// Generated on 30/06/2022, 16:20:58
+// Source: design-tokens/componenets/global/global-forms/default.json


Spelling mistake: componenets should be components
across this and springer

whoops!

I had a bit of a re-think on this, as an aside.

The current npm scripts for generating the Sass variables are a pretty blunt tool in generating literal and alias tokens (pretty much) every time.

I'm going to rework it so that they're either very separate tasks or the script checks for changes to disc for the.json files and only compiles things that have changed.

Moving forward, it should be the case that literal tokens very rarely get changed. alias tokens do get changed but not often, and component tokensonly get changed/added to when there are changes from thealiastokens or we are introducingcomponent` tokens to the component.

If that makes sense.

sturobson · 2022-07-01T21:28:25Z

with the linting failing on shortened hex color codes (or them not being shortened) hadn’t failed when they were introduced in the brand-context - This issue should soon be irrelevant when we switch back on the output to reference the alias token Sass variables.

amyhupe

OK, here's my review. Mostly small things, aimed at:

increasing consistency of terminology, as much as possible
referencing user impact, where appropriate
simplifying language

I've also suggested copy changes to some of the example copy we're using. My general take on this is that example copy should be obviously an example (e.g. Monkey, Platypus etc.) or realistic, and something we'd be happy to be used in a real service.

I hope these comments make sense - let me know if anything needs clarifying. And good work - this is an absolute beast!

toolkits/global/packages/global-forms/README.md

amyhupe · 2022-07-04T09:46:16Z

toolkits/global/packages/global-forms/README.md


-## Branding
+This component comprises a number of form fields and related templates. It is designed to make constructing any variety of HTML form a relatively straightforward process. 


Suggested change

This component comprises a number of form fields and related templates. It is designed to make constructing any variety of HTML form a relatively straightforward process.

This component includes a number of form fields and related templates. It is designed to make it as simple as possible to create an HTML form.

amyhupe · 2022-07-04T09:50:24Z

toolkits/global/packages/global-forms/README.md


-The `global-forms` component currently uses the `DEFAULT` brand only.
+The component does not ship with any JavaScript. States (such as an invalid/error state) are defined at a data level. Implementations using client-side processing/validation may benefit from compiling the form’s (handlebars) template in the browser.


Suggested change

The component does not ship with any JavaScript. States (such as an invalid/error state) are defined at a data level. Implementations using client-side processing/validation may benefit from compiling the form’s (handlebars) template in the browser.

The component does not include any JavaScript. States (such as an invalid/error state) are defined at a data level. If you're using client-side processing, you might benefit from compiling the form’s handlebars template in the browser.

amyhupe · 2022-07-04T10:01:16Z

toolkits/global/packages/global-forms/README.md

+There are two options for rendering form fields: 
+
+1. Compile each field independently, using its respective template from the `view/fields` folder.
+2. Organize your fields into fieldsets using the data structure exemplified in `demo/context.json`. In this case, you will have to iterate over a `fieldsets` property something like this:


I know there's still a question mark over whether we use US or UK English in SN, but I've been using UK English in the docs so far so I'm changing it here for consistency.

Suggested change

2. Organize your fields into fieldsets using the data structure exemplified in `demo/context.json`. In this case, you will have to iterate over a `fieldsets` property something like this:

2. Organise your fields into `fieldset`s using the data structure shown in `demo/context.json`. In this case, you'll have to iterate over a `fieldsets` property something like this:

amyhupe · 2022-07-04T10:01:59Z

toolkits/global/packages/global-forms/README.md

+There are two options for rendering form fields: 
+
+1. Compile each field independently, using its respective template from the `view/fields` folder.
+2. Organize your fields into fieldsets using the data structure exemplified in `demo/context.json`. In this case, you will have to iterate over a `fieldsets` property something like this:


I don't fully understand what "iterate over a fieldsets property" means - maybe this will make sense to FEDs but just wanted to see if you think it could do with clarifying?

Putting"over a fieldsets array" to make it more explicit what the iteration refers to.

amyhupe · 2022-07-04T15:02:57Z

toolkits/global/packages/global-forms/demo/context.json

+						"template": "text",
+						"label": "Your name (with error)",
+						"hint": "Your name is on your passport",
+						"error": "That is not a name, it’s a number",


Suggested change

"error": "That is not a name, it’s a number",

"error": "Enter your name",

amyhupe · 2022-07-04T15:03:48Z

toolkits/global/packages/global-forms/demo/context.json

+					{
+						"template": "checkbox",
+						"label": "Agree to our terms (with error)",
+						"error": "You must agree to the terms before continuing.",


Updating to keep consistent with my previous suggestions:

Suggested change

"error": "You must agree to the terms before continuing.",

"error": "Agree to the terms to continue.",

amyhupe · 2022-07-04T15:04:59Z

toolkits/global/packages/global-forms/demo/context.json

+					{
+						"template": "checkbox",
+						"label": "Agree to our terms (with hint)",
+						"hint": "You should have read these. Read them, then agree to them.",


Changing to something I'd be happy to see in a real service

Suggested change

"hint": "You should have read these. Read them, then agree to them.",

"hint": "You must agree to the terms to continue your application",

amyhupe · 2022-07-04T15:05:22Z

toolkits/global/packages/global-forms/demo/context.json

+						"template": "checkbox",
+						"label": "Agree to our terms (with error)",
+						"error": "You must agree to the terms before continuing.",
+						"hint": "You should have read these. Read them, then agree to them.",


As before

Suggested change

"hint": "You should have read these. Read them, then agree to them.",

"hint": "You must agree to the terms to continue your application.",

amyhupe · 2022-07-04T15:06:12Z

toolkits/global/packages/global-forms/README.md

@@ -13,3 +17,265 @@ The `global-forms` component currently uses the `DEFAULT` brand only.
 // Include this with your other components
 @import '@springernature/global-forms/scss/50-components/forms';
 ```
+
+Then you will need to register the Handlebars partials in the `/view` folder. 


For consistency:

Suggested change

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.

as a long time owner of Sassnotsass.com I had a quick look at the docs for handlebars … and although the logo is in lowercase they seem to use Title Case when it's mentioned throughout the docs.

(I'm happy either way 😄)

…oolkits into form-templates

sturobson · 2022-07-05T08:02:41Z

@alexkilgour I think this PR … would be a good chance to clean up the issues list … as I spotted this last night -- #485 -- I'm assuming some of these would be nullified with this PR?

aliuk2012 · 2022-07-05T09:12:37Z

toolkits/global/packages/global-forms/view/label.hbs

@@ -0,0 +1,6 @@
+<label for="{{id}}" class="c-forms__label">
+	{{label}}{{#if optional}} (optional){{/if}}


🤔 I don't think "optional" is really helpful for the following reasons

By default all text fields are "optional" i.e they dont have "required" set to true.

This will not be useful if the service has to support multiple languages because the copy is not translated.

When I worked in GOV we tried to make all fields required by default (no point asking a user for data if its not useful for all) and only flag up "optional" fields in the label like what is done here but in our case the text fields are not required by default so seems to send mix messages as to when to use this option or not.

Instead just let the devs control the copy and if they want to use "(Optional)" they could just include it in their copy that they need for the label.

The determination of what is optional or not, or what copy should be used would come from agreement across dsign/ux/content that would ultimately end up in the Design System docs site?

Instead just let the devs control the copy and if they want to use "(Optional)" they could just include it in their copy that they need for the label.

From a content design point of view, I'd really like to introduce some standardisation if possible. I get that we're not currently offering localisation of this copy, but we're not currently doing that for the content elements of any components so this isn't a new problem. My concern is if we don't include something, people are going to fall back to using asterisks.

So, @Heydon has followed the Sketch designs (see screenshot). I'd have to check with James (on holiday until Monday (11/07/22) but I think all of the form designs have gone through rounds of review in SN digital and this is currently the latest agreed across discipline.

regarding the issue with translation. It could be made a handlebars variable in the json, rather than hardcoded as it is now‽ So it could get switched out as needed? (pinging @Heydon)

Microcopy like (optional) here could also be tokenised -- which could further help documentation of it all

I was just following the UX. Can we discuss this after v1 is out, please? For the time being, just put required: true on all your fields if you want them all required.

toolkits/global/packages/global-forms/README.md

amyhupe

Hello,

A few additional revisions on yesterday's revisions. These are things I think could be better clarified, on a second read, or where copy errors have been introduced in the process of suggesting & accepting changes.

amyhupe · 2022-07-05T10:57:17Z

toolkits/global/packages/global-forms/README.md

+}
+```
+
+If you do wish to include a legend, you can use HTML to style it and add semantic meaning. It is recommended to use a heading of the correct level as the legend content.


Suggesting another small revision to this to make the second sentence active, not passive.

Suggested change

If you do wish to include a legend, you can use HTML to style it and add semantic meaning. It is recommended to use a heading of the correct level as the legend content.

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.

amyhupe · 2022-07-05T11:07:04Z

toolkits/global/packages/global-forms/README.md

+
+### Fields
+
+Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.


Something went awry with the resolving of these edits. Fixed:

Suggested change

Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. 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": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.

amyhupe · 2022-07-05T11:21:43Z

toolkits/global/packages/global-forms/README.md

+
+Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.
+
+This component supports a wide range of standard form field attributes. So, for example, to include a `readonly` attribute on your text input, you  can include a property of the same name on the data:


Suggested change

This component supports a wide range of standard form field attributes. So, for example, to include a `readonly` attribute on your text input, you can include a property of the same name on the data:

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:

amyhupe · 2022-07-05T11:23:00Z

toolkits/global/packages/global-forms/README.md

+}
+```
+
+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:


Suggested change

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 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:

amyhupe · 2022-07-05T11:27:41Z

toolkits/global/packages/global-forms/README.md

+
+### Making choices
+
+`Select` fields (using the `<select>` element) define their choices via an `options` property, which must be an array. The `selected` property is a Boolean:


I think it's good to specify what "their choices" refer to. I know this is technical documentation, but the more we can do to contextualise it for designers now, the less we'll have to edit later when we layer in the design guidelines.

Suggested change

`Select` fields (using the `<select>` element) define their choices via an `options` property, which must be an array. The `selected` property is a Boolean:

`Select` fields (using the `<select>` element) define the user's answer choices with an `options` property, which must be an array. The `selected` property is a Boolean:

amyhupe · 2022-07-05T11:28:39Z

toolkits/global/packages/global-forms/README.md

+
+Radios are always grouped together in a `fieldset`, so the group label (“Animal”, here) renders as a `legend` not a `label`.
+
+You might want to show users an additional field when they select a radio. For example, revealing a text input field for them to give more specific information about the option they’ve selected. 


Suggested change

You might want to show users an additional field when they select a radio. For example, revealing a text input field for them to give more specific information about the option they’ve selected.

You might want to show users an additional field when they select a particular radio. For example, revealing a text input field for them to give more specific information about the option they’ve selected.

toolkits/global/packages/global-forms/README.md

amyhupe · 2022-07-05T11:30:27Z

toolkits/global/packages/global-forms/README.md

+### Buttons
+
+A `template` of `buttons` defines a set of button controls, displayed inline (using Flexbox and `gap` for tidy wrapping). 
+The `type` property for each individual button corresponds to the `type` property/attribute. For example, here is how you would include a submit button:


Can we make a choice here between property and attribute, and lose the slash? If it really could be either, can we say "or"?

sturobson

"It's been a long road. Getting from there to here. It's been a long time. But the time is finally near."

I think we're now in a good place to release this as an rc1 version.

Buyer Beware! There may be dragons!

Great work @Heydon and all involved in recreating global-forms for 2022 and beyond, finding bugs, questioning and improving things so rc1 is pretty solid out of the gate.

Heydon added 4 commits May 4, 2022 17:17

basic partials architecture

78db2ac

error and error icon

20ac21e

select template

2076f97

textarea

22001ac

Heydon added role: FED DO NOT MERGE labels May 5, 2022

Heydon and others added 24 commits May 6, 2022 09:32

template hierarchy, logo, and BEM

86624eb

classes named after component

6c0745c

renaming and reorganization of partials

d8c2cdb

checkbox input and improved structure

8a503cc

basic file upload

0172a8e

basic colors

32ef2f4

basic style settings using tokens where applicable

7fe58ee

legend allowing headings

f970968

initial styling (text inputs)

0df4400

select and radio styling

0a2ae35

adds component tokens build step

a9f93e1

adds default brand global component tokens build step

3b7d7f5

adds new aliases

7d3f87e

adds default footer tokens

a42f265

updates generated aliases

79ef9de

adds forms default sass files

4594502

global icons and radio secreted fields

b8c7769

adds more borders

00a1e6f

adds indent to forms

3d25034

updates package json to do all global component brands

f0c8b70

updates alias compiled sass files

282d3c7

global forms default styles

f8ae023

missing global brand variant generators

8cccf4d

fixes if else statement for comment generation in sass files

001d91f

alexkilgour reviewed Jul 1, 2022

View reviewed changes

Heydon added 12 commits July 1, 2022 10:25

springernature and nature brand tweaks

a267c79

radio spacing

56b0cf0

copy change for clarity over select[multiple]

9c9cee4

classes note

d7a7085

revert class stuff

4750107

remove legend heading margin, use stacking

446464c

stronger legend avice

911b007

'type' terminology to 'template'

9a99dd9

versioning

22c3024

README warning

18bc17b

chore: add missing trailing semicolon

94b24cb

colors to three digits

f5fd593

Heydon and others added 4 commits July 4, 2022 09:05

fieldset reference -> fieldsets

5404871

qualified code syntax

6054ce4

update sass-lint config to allow for long form hex codes

47da5df

Merge branch 'master' into form-templates

eb52f4c

amyhupe reviewed Jul 4, 2022

View reviewed changes

Heydon added 2 commits July 4, 2022 17:36

docs changes, thanks Amy

0ab79c1

Merge branch 'form-templates' of github.com:springernature/frontend-t…

5132d88

…oolkits into form-templates

aliuk2012 reviewed Jul 5, 2022

View reviewed changes

toolkits/global/packages/global-forms/README.md Show resolved Hide resolved

amyhupe reviewed Jul 5, 2022

View reviewed changes

Heydon added 2 commits July 5, 2022 13:30

AMy second pass

29017c0

arbitrary attributes support

b7ca29b

sturobson approved these changes Jul 6, 2022

View reviewed changes

Heydon merged commit ab63ab5 into master Jul 6, 2022

sturobson deleted the form-templates branch July 6, 2022 15:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Global Forms #743

Global Forms #743

Heydon commented May 5, 2022 •

edited

Loading

alexkilgour Jul 1, 2022

sturobson Jul 1, 2022

sturobson commented Jul 1, 2022

amyhupe left a comment

amyhupe Jul 4, 2022

amyhupe Jul 4, 2022

amyhupe Jul 4, 2022

amyhupe Jul 4, 2022

Heydon Jul 4, 2022

amyhupe Jul 4, 2022

amyhupe Jul 4, 2022

amyhupe Jul 4, 2022 •

edited

Loading

amyhupe Jul 4, 2022 •

edited

Loading

amyhupe Jul 4, 2022

sturobson Jul 4, 2022 •

edited

Loading

sturobson commented Jul 5, 2022

aliuk2012 Jul 5, 2022

aliuk2012 Jul 5, 2022

sturobson Jul 5, 2022

amyhupe Jul 5, 2022

sturobson Jul 5, 2022

sturobson Jul 5, 2022

Heydon Jul 5, 2022

amyhupe left a comment

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

amyhupe Jul 5, 2022

sturobson left a comment

		@@ -0,0 +1,34 @@
		// Generated on 30/06/2022, 16:20:58
		// Source: design-tokens/componenets/global/global-forms/default.json


		## Branding
		This component comprises a number of form fields and related templates. It is designed to make constructing any variety of HTML form a relatively straightforward process.

	This component comprises a number of form fields and related templates. It is designed to make constructing any variety of HTML form a relatively straightforward process.
	This component includes a number of form fields and related templates. It is designed to make it as simple as possible to create an HTML form.


		The `global-forms` component currently uses the `DEFAULT` brand only.
		The component does not ship with any JavaScript. States (such as an invalid/error state) are defined at a data level. Implementations using client-side processing/validation may benefit from compiling the form’s (handlebars) template in the browser.

	The component does not ship with any JavaScript. States (such as an invalid/error state) are defined at a data level. Implementations using client-side processing/validation may benefit from compiling the form’s (handlebars) template in the browser.
	The component does not include any JavaScript. States (such as an invalid/error state) are defined at a data level. If you're using client-side processing, you might benefit from compiling the form’s handlebars template in the browser.

	2. Organize your fields into fieldsets using the data structure exemplified in `demo/context.json`. In this case, you will have to iterate over a `fieldsets` property something like this:
	2. Organise your fields into `fieldset`s using the data structure shown in `demo/context.json`. In this case, you'll have to iterate over a `fieldsets` property something like this:

	"error": "That is not a name, it’s a number",
	"error": "Enter your name",

	"error": "You must agree to the terms before continuing.",
	"error": "Agree to the terms to continue.",

	"hint": "You should have read these. Read them, then agree to them.",
	"hint": "You must agree to the terms to continue your application",

	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.

		@@ -0,0 +1,6 @@
		<label for="{{id}}" class="c-forms__label">
		{{label}}{{#if optional}} (optional){{/if}}

	If you do wish to include a legend, you can use HTML to style it and add semantic meaning. It is recommended to use a heading of the correct level as the legend content.
	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.


		### Fields

		Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.

	Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. 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": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.


		Fields take the `template` property to determine which of the `view/fields` template files they represent. This property along with `label`, `id`, and The `template` property sets the type of field - for example, `"template": "text"` renders a text input field. Aim to make the `template`, `label`, `id`, and `name` properties mandatory parts of your data schema.

		This component supports a wide range of standard form field attributes. So, 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 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:


		### Making choices

		`Select` fields (using the `<select>` element) define their choices via an `options` property, which must be an array. The `selected` property is a Boolean:


		Radios are always grouped together in a `fieldset`, so the group label (“Animal”, here) renders as a `legend` not a `label`.

		You might want to show users an additional field when they select a radio. For example, revealing a text input field for them to give more specific information about the option they’ve selected.

Global Forms #743

Global Forms #743

Conversation

Heydon commented May 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sturobson commented Jul 1, 2022

amyhupe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyhupe Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

amyhupe Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sturobson Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

sturobson commented Jul 5, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyhupe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sturobson left a comment

Choose a reason for hiding this comment

Heydon commented May 5, 2022 •

edited

Loading

amyhupe Jul 4, 2022 •

edited

Loading

amyhupe Jul 4, 2022 •

edited

Loading

sturobson Jul 4, 2022 •

edited

Loading