From 520feeeba94963330f852178475f5ba14394cec1 Mon Sep 17 00:00:00 2001
From: Maximilian Franzke <787658+mfranzke@users.noreply.github.com>
Date: Fri, 15 Dec 2023 08:54:38 +0100
Subject: [PATCH] feat(form elements): provide possibility to visually hide the
 label (#628)

* feat: provide general styling for visually hidden labels

* docs: typo

* feat: provided the possibility for all forms to visually hide the label

* feat: provided the possibility for all forms to visually hide the label

* Update _form-elements.scss

* refactor: added missing references

* refactor: not providing an empty option on hidden label
---
 source/_patterns/01-elements/_form-elements.scss |  6 ++++++
 .../_patterns/01-elements/checkbox/checkbox.hbs  |  2 +-
 .../_patterns/01-elements/checkbox/checkbox.scss |  3 +++
 .../checkbox/checkbox~indeterminate.md           |  2 +-
 .../checkbox/checkbox~label-hidden.json          |  4 ++++
 .../checkbox/checkbox~label-hidden.md            | 11 +++++++++++
 .../checkbox~on-dark-background-indeterminate.md |  2 +-
 source/_patterns/01-elements/input/input.hbs     |  3 ++-
 source/_patterns/01-elements/input/input.scss    | 16 +++++++++++++---
 .../01-elements/input/input~hidden-label.json    |  4 ++++
 .../01-elements/input/input~hidden-label.md      | 13 +++++++++++++
 source/_patterns/01-elements/radio/_radio.hbs    |  2 +-
 source/_patterns/01-elements/radio/radio.scss    |  4 ++++
 source/_patterns/01-elements/radio/radios.hbs    |  2 +-
 .../01-elements/radio/radios~label-hidden.json   |  4 ++++
 .../01-elements/radio/radios~label-hidden.md     | 11 +++++++++++
 source/_patterns/01-elements/select/select.hbs   |  4 ++--
 source/_patterns/01-elements/select/select.scss  |  7 +++++++
 .../01-elements/select/select~hidden-label.json  |  5 +++++
 .../01-elements/select/select~hidden-label.md    | 13 +++++++++++++
 .../_patterns/01-elements/textarea/textarea.hbs  |  2 +-
 .../_patterns/01-elements/textarea/textarea.scss |  5 +++++
 .../textarea/textarea~hidden-label.json          |  5 +++++
 .../textarea/textarea~hidden-label.md            | 13 +++++++++++++
 24 files changed, 131 insertions(+), 12 deletions(-)
 create mode 100644 source/_patterns/01-elements/checkbox/checkbox~label-hidden.json
 create mode 100644 source/_patterns/01-elements/checkbox/checkbox~label-hidden.md
 create mode 100644 source/_patterns/01-elements/input/input~hidden-label.json
 create mode 100644 source/_patterns/01-elements/input/input~hidden-label.md
 create mode 100644 source/_patterns/01-elements/radio/radios~label-hidden.json
 create mode 100644 source/_patterns/01-elements/radio/radios~label-hidden.md
 create mode 100644 source/_patterns/01-elements/select/select~hidden-label.json
 create mode 100644 source/_patterns/01-elements/select/select~hidden-label.md
 create mode 100644 source/_patterns/01-elements/textarea/textarea~hidden-label.json
 create mode 100644 source/_patterns/01-elements/textarea/textarea~hidden-label.md

diff --git a/source/_patterns/01-elements/_form-elements.scss b/source/_patterns/01-elements/_form-elements.scss
index d88bff7d20..edd678234b 100644
--- a/source/_patterns/01-elements/_form-elements.scss
+++ b/source/_patterns/01-elements/_form-elements.scss
@@ -33,6 +33,12 @@
 	}
 }
 
+%form-label {
+	&[data-label-hidden="true"] {
+		@include a11y-visually-hidden($partial: $partial);
+	}
+}
+
 // ### Style variations
 // Semitransparent
 %form-element-semitransparent {
diff --git a/source/_patterns/01-elements/checkbox/checkbox.hbs b/source/_patterns/01-elements/checkbox/checkbox.hbs
index 0dc76c072c..eec60f4aa1 100644
--- a/source/_patterns/01-elements/checkbox/checkbox.hbs
+++ b/source/_patterns/01-elements/checkbox/checkbox.hbs
@@ -5,7 +5,7 @@
 	value="{{ value }}"
 	{{#if describedbyid }} aria-describedby="{{ describedbyid }}"{{/if }}
 	{{#if invalid }} aria-invalid="{{ invalid }}"{{/if }}>
-<label class="elm-label" for="{{ id }}">{{ label }}</label>
+<label class="elm-label" for="{{ id }}"{{#if labelHidden }} data-label-hidden="true"{{/if }}>{{ label }}</label>
 {{#if indeterminate}}
 <script>
 	document.querySelector('#{{ id }}').indeterminate = true;
diff --git a/source/_patterns/01-elements/checkbox/checkbox.scss b/source/_patterns/01-elements/checkbox/checkbox.scss
index 4751e36bba..e1dd03763e 100644
--- a/source/_patterns/01-elements/checkbox/checkbox.scss
+++ b/source/_patterns/01-elements/checkbox/checkbox.scss
@@ -2,6 +2,7 @@
 
 @import "../../../css/partials.meta";
 @import "checkbox.variables";
+@import "../form-elements";
 
 .elm-checkbox {
 	@include icon("\00A0", 24, "outline", $partial: $partial);
@@ -64,6 +65,8 @@
 	}
 
 	& + label {
+		@extend %form-label;
+
 		margin-left: $db-spacing-xs;
 	}
 }
diff --git a/source/_patterns/01-elements/checkbox/checkbox~indeterminate.md b/source/_patterns/01-elements/checkbox/checkbox~indeterminate.md
index b4085c2c7c..52418644f2 100644
--- a/source/_patterns/01-elements/checkbox/checkbox~indeterminate.md
+++ b/source/_patterns/01-elements/checkbox/checkbox~indeterminate.md
@@ -4,7 +4,7 @@ title: Checkbox - indeterminate
 
 ## State: indeterminate
 
-Please keep in mind, that the special state of an indeterminate element is necessary to get set programatically with JavaScript:
+Please keep in mind, that the special state of an indeterminate element is necessary to get set programmatically with JavaScript:
 
 ```js
 inputInstance.indeterminate = true;
diff --git a/source/_patterns/01-elements/checkbox/checkbox~label-hidden.json b/source/_patterns/01-elements/checkbox/checkbox~label-hidden.json
new file mode 100644
index 0000000000..fd63e8d6ef
--- /dev/null
+++ b/source/_patterns/01-elements/checkbox/checkbox~label-hidden.json
@@ -0,0 +1,4 @@
+{
+	"id": "checkbox05",
+	"labelHidden": true
+}
diff --git a/source/_patterns/01-elements/checkbox/checkbox~label-hidden.md b/source/_patterns/01-elements/checkbox/checkbox~label-hidden.md
new file mode 100644
index 0000000000..83e001af4c
--- /dev/null
+++ b/source/_patterns/01-elements/checkbox/checkbox~label-hidden.md
@@ -0,0 +1,11 @@
+---
+title: Checkbox - Hidden label
+---
+
+## Possibility to hide the label
+
+> A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users.
+
+source: <https://www.w3.org/WAI/tutorials/forms/labels/#hiding-label-text>
+
+You could set the attribute `data-label-hidden="true"` for the rare case that you would want to visually hide the textual label for a checkbox element.
diff --git a/source/_patterns/01-elements/checkbox/checkbox~on-dark-background-indeterminate.md b/source/_patterns/01-elements/checkbox/checkbox~on-dark-background-indeterminate.md
index 48d25c1c8b..1abd62817a 100644
--- a/source/_patterns/01-elements/checkbox/checkbox~on-dark-background-indeterminate.md
+++ b/source/_patterns/01-elements/checkbox/checkbox~on-dark-background-indeterminate.md
@@ -4,7 +4,7 @@ title: Checkbox - indeterminate on dark background
 
 ## State: indeterminate
 
-Please keep in mind, that the special state of an indeterminate element is necessary to get set programatically with JavaScript:
+Please keep in mind, that the special state of an indeterminate element is necessary to get set programmatically with JavaScript:
 
 ```js
 inputInstance.indeterminate = true;
diff --git a/source/_patterns/01-elements/input/input.hbs b/source/_patterns/01-elements/input/input.hbs
index 4d87165cf9..3862c3efe0 100644
--- a/source/_patterns/01-elements/input/input.hbs
+++ b/source/_patterns/01-elements/input/input.hbs
@@ -15,7 +15,8 @@
 <label class="elm-label"
 	for="{{ id }}"
 	aria-hidden="true"
-	id="{{ id }}-label">{{ label }}</label>
+	id="{{ id }}-label"
+	{{#if labelHidden }} data-label-hidden="true"{{/if }}>{{ label }}</label>
 {{#if description }}<p{{#if describedbyid }} id="{{ describedbyid }}"{{/if }} class="description">{{{ description }}}</p>{{/if }}
 {{#if datalist }}<datalist id="datalist{{ id }}">
 	{{#each datalistItems }}
diff --git a/source/_patterns/01-elements/input/input.scss b/source/_patterns/01-elements/input/input.scss
index 341f670010..aee1d30e9b 100644
--- a/source/_patterns/01-elements/input/input.scss
+++ b/source/_patterns/01-elements/input/input.scss
@@ -1,5 +1,6 @@
 @charset "utf-8";
 
+@import "../../../css/partials.meta";
 @import "input.variables";
 @import "../form-elements";
 
@@ -13,10 +14,14 @@
 	line-height: to-rem($pxValue: 24);
 	max-width: 100%;
 
-	padding: $db-spacing-s $db-spacing-m;
-
 	width: 100%;
 
+	padding-inline: $db-spacing-m;
+	// No need to reposition the included value on hidden label
+	&:not(:has(+ label[data-label-hidden="true"])) {
+		padding-block: $db-spacing-s;
+	}
+
 	&[list] {
 		&::-webkit-calendar-picker-indicator {
 			margin-right: -1rem;
@@ -25,7 +30,10 @@
 
 	&:not(:placeholder-shown) {
 		padding-bottom: 0;
-		padding-top: to-rem($pxValue: 16);
+		// No need to reposition the included value on hidden label
+		&:not(:has(+ label[data-label-hidden="true"])) {
+			padding-top: to-rem($pxValue: 16);
+		}
 	}
 
 	// * TODO: to get evaluated
@@ -89,6 +97,8 @@
 		}
 
 		& + .elm-label {
+			@extend %form-label;
+
 			color: $db-color-cool-gray-500;
 			display: block;
 			font-size: to-rem($pxValue: 12);
diff --git a/source/_patterns/01-elements/input/input~hidden-label.json b/source/_patterns/01-elements/input/input~hidden-label.json
new file mode 100644
index 0000000000..5e264b5da2
--- /dev/null
+++ b/source/_patterns/01-elements/input/input~hidden-label.json
@@ -0,0 +1,4 @@
+{
+	"id": "input20",
+	"labelHidden": "true"
+}
diff --git a/source/_patterns/01-elements/input/input~hidden-label.md b/source/_patterns/01-elements/input/input~hidden-label.md
new file mode 100644
index 0000000000..2071c3cdba
--- /dev/null
+++ b/source/_patterns/01-elements/input/input~hidden-label.md
@@ -0,0 +1,13 @@
+---
+title: Input - Hidden label
+state: complete
+order: 11
+---
+
+## Possibility to hide the label
+
+> A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users.
+
+source: <https://www.w3.org/WAI/tutorials/forms/labels/#hiding-label-text>
+
+You could set the attribute `data-label-hidden="true"` for the rare case that you would want to visually hide the textual label for a input element.
diff --git a/source/_patterns/01-elements/radio/_radio.hbs b/source/_patterns/01-elements/radio/_radio.hbs
index c704188402..7c76f4b8ab 100644
--- a/source/_patterns/01-elements/radio/_radio.hbs
+++ b/source/_patterns/01-elements/radio/_radio.hbs
@@ -8,4 +8,4 @@
 	{{#if describedbyid }} aria-describedby="{{ describedbyid }}"{{/if }}
 	{{#if invalid}} aria-invalid="true"{{/if }}
 	{{#if required}} required{{/if}}>
-<label class="elm-label" for="{{ id }}">{{ label }}</label>
+<label class="elm-label" for="{{ id }}"{{#if labelHidden }} data-label-hidden="true"{{/if }}>{{ label }}</label>
diff --git a/source/_patterns/01-elements/radio/radio.scss b/source/_patterns/01-elements/radio/radio.scss
index 0a9cdcc7da..8e4db1287f 100644
--- a/source/_patterns/01-elements/radio/radio.scss
+++ b/source/_patterns/01-elements/radio/radio.scss
@@ -1,6 +1,8 @@
 @charset "utf-8";
 
+@import "../../../css/partials.meta";
 @import "radio.variables";
+@import "../form-elements";
 
 .elm-radio {
 	appearance: none;
@@ -52,6 +54,8 @@
 	// }
 
 	& + label {
+		@extend %form-label;
+
 		margin-left: $db-spacing-xs;
 	}
 
diff --git a/source/_patterns/01-elements/radio/radios.hbs b/source/_patterns/01-elements/radio/radios.hbs
index 72d987a589..21a276a5a2 100644
--- a/source/_patterns/01-elements/radio/radios.hbs
+++ b/source/_patterns/01-elements/radio/radios.hbs
@@ -1,3 +1,3 @@
 {{#each radios }}
-	{{> elements-radio disabled=../disabled invalid=../invalid required=../required id=(unique-id) name=../name }}<br>
+	{{> elements-radio disabled=../disabled invalid=../invalid required=../required id=(unique-id) name=../name labelHidden=../labelHidden }}<br>
 {{/each }}
diff --git a/source/_patterns/01-elements/radio/radios~label-hidden.json b/source/_patterns/01-elements/radio/radios~label-hidden.json
new file mode 100644
index 0000000000..e05de37378
--- /dev/null
+++ b/source/_patterns/01-elements/radio/radios~label-hidden.json
@@ -0,0 +1,4 @@
+{
+	"name": "radioLabelHidden",
+	"labelHidden": true
+}
diff --git a/source/_patterns/01-elements/radio/radios~label-hidden.md b/source/_patterns/01-elements/radio/radios~label-hidden.md
new file mode 100644
index 0000000000..3dabcf991c
--- /dev/null
+++ b/source/_patterns/01-elements/radio/radios~label-hidden.md
@@ -0,0 +1,11 @@
+---
+title: Radio - Hidden label
+---
+
+## Possibility to hide the label
+
+> A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users.
+
+source: <https://www.w3.org/WAI/tutorials/forms/labels/#hiding-label-text>
+
+You could set the attribute `data-label-hidden="true"` for the rare case that you would want to visually hide the textual label for a radio element.
diff --git a/source/_patterns/01-elements/select/select.hbs b/source/_patterns/01-elements/select/select.hbs
index 13bed7c5c4..381b73da96 100644
--- a/source/_patterns/01-elements/select/select.hbs
+++ b/source/_patterns/01-elements/select/select.hbs
@@ -5,7 +5,7 @@
 	{{#if required}} required{{/if}}
 	{{#if invalid }} aria-invalid="{{ invalid }}" {{/if }}
 	{{#if variant}} data-variant="{{variant}}"{{/if }}>
-	{{#if optgroup}}<optgroup label="Devices">{{else}}{{#unless multiple}}<option></option>{{/unless}}{{/if }}
+	{{#if optgroup}}<optgroup label="Devices">{{else}}{{#unless multiple}}{{#unless labelHidden}}<option></option>{{/unless}}{{/unless}}{{/if }}
 		<option value="smartphone">Smartphone</option>
 		<option value="softphone">Softphone</option>
 		<option value="headset">Headset</option>
@@ -18,4 +18,4 @@
 		<option value="developer">Developer</option>
 	</optgroup>{{/if }}
 </select>
-<label class="elm-label" for="{{ id }}">{{ label }}</label>
+<label class="elm-label" for="{{ id }}"{{#if labelHidden }} data-label-hidden="true"{{/if }}>{{ label }}</label>
diff --git a/source/_patterns/01-elements/select/select.scss b/source/_patterns/01-elements/select/select.scss
index 9ea18caf8f..aefa0f6990 100644
--- a/source/_patterns/01-elements/select/select.scss
+++ b/source/_patterns/01-elements/select/select.scss
@@ -1,3 +1,4 @@
+@import "../../../css/partials.meta";
 @import "select.variables";
 @import "../form-elements";
 @import "../../../css/db-ui-core.variables";
@@ -27,6 +28,10 @@
 		background-repeat: no-repeat;
 		height: to-rem($pxValue: 44);
 		padding: to-rem($pxValue: 20) to-rem($pxValue: 42) 0 $db-spacing-m;
+		// No need to reposition the included value on hidden label
+		&:has(+ label[data-label-hidden="true"]) {
+			padding-top: 0;
+		}
 
 		// Floating labels
 		& + .elm-label {
@@ -96,6 +101,8 @@
 
 	// Floating labels
 	& + .elm-label {
+		@extend %form-label;
+
 		display: block;
 		font-size: to-rem($pxValue: 12);
 		margin-bottom: -#{to-rem($pxValue: 18)};
diff --git a/source/_patterns/01-elements/select/select~hidden-label.json b/source/_patterns/01-elements/select/select~hidden-label.json
new file mode 100644
index 0000000000..0e6601012a
--- /dev/null
+++ b/source/_patterns/01-elements/select/select~hidden-label.json
@@ -0,0 +1,5 @@
+{
+	"id": "select14",
+	"label": "Devices",
+	"labelHidden": "true"
+}
diff --git a/source/_patterns/01-elements/select/select~hidden-label.md b/source/_patterns/01-elements/select/select~hidden-label.md
new file mode 100644
index 0000000000..c69333dbee
--- /dev/null
+++ b/source/_patterns/01-elements/select/select~hidden-label.md
@@ -0,0 +1,13 @@
+---
+title: Select - Hidden label
+state: complete
+order: 8
+---
+
+## Possibility to hide the label
+
+> A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users.
+
+source: <https://www.w3.org/WAI/tutorials/forms/labels/#hiding-label-text>
+
+You could set the attribute `data-label-hidden="true"` for the rare case that you would want to visually hide the textual label for a select element.
diff --git a/source/_patterns/01-elements/textarea/textarea.hbs b/source/_patterns/01-elements/textarea/textarea.hbs
index 0f31ddae86..063011e47f 100644
--- a/source/_patterns/01-elements/textarea/textarea.hbs
+++ b/source/_patterns/01-elements/textarea/textarea.hbs
@@ -1,5 +1,5 @@
 {{! TODO: the retrieval of the standard values doesn't work so far }}
-<label class="elm-label" for="{{ id }}">{{ label }}</label>
+<label class="elm-label" for="{{ id }}"{{#if labelHidden }} data-label-hidden="true"{{/if }}>{{ label }}</label>
 <textarea class="elm-textarea {{ styleModifier }}"
 	placeholder="{{ placeholder }}"
 	id="{{ id }}"
diff --git a/source/_patterns/01-elements/textarea/textarea.scss b/source/_patterns/01-elements/textarea/textarea.scss
index ee0f6437ce..79a4519220 100644
--- a/source/_patterns/01-elements/textarea/textarea.scss
+++ b/source/_patterns/01-elements/textarea/textarea.scss
@@ -1,5 +1,6 @@
 @charset "utf-8";
 
+@import "../../../css/partials.meta";
 @import "textarea.variables";
 @import "../form-elements";
 
@@ -29,6 +30,10 @@
 	// align-items: center;
 	// justify-content: flex-start;
 
+	.elm-label:has(+ &) {
+		@extend %form-label;
+	}
+
 	&:not([rows]) {
 		max-height: to-rem($pxValue: 600);
 		min-height: to-rem($pxValue: 120);
diff --git a/source/_patterns/01-elements/textarea/textarea~hidden-label.json b/source/_patterns/01-elements/textarea/textarea~hidden-label.json
new file mode 100644
index 0000000000..9f5ef14c1d
--- /dev/null
+++ b/source/_patterns/01-elements/textarea/textarea~hidden-label.json
@@ -0,0 +1,5 @@
+{
+	"id": "textarea08",
+	"value": "Input",
+	"labelHidden": "true"
+}
diff --git a/source/_patterns/01-elements/textarea/textarea~hidden-label.md b/source/_patterns/01-elements/textarea/textarea~hidden-label.md
new file mode 100644
index 0000000000..bd65ece300
--- /dev/null
+++ b/source/_patterns/01-elements/textarea/textarea~hidden-label.md
@@ -0,0 +1,13 @@
+---
+title: Textarea - Hidden label
+state: complete
+order: 8
+---
+
+## Possibility to hide the label
+
+> A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users.
+
+source: <https://www.w3.org/WAI/tutorials/forms/labels/#hiding-label-text>
+
+You could set the attribute `data-label-hidden="true"` for the rare case that you would want to visually hide the textual label for a textarea element.