From a41757f6c861637a3f42a83eaec80a7d2dd36580 Mon Sep 17 00:00:00 2001
From: karwosts <32912880+karwosts@users.noreply.github.com>
Date: Wed, 29 May 2024 05:33:17 -0700
Subject: [PATCH] Document blueprint input sections (#32769)

* Document blueprint input sections

* Update schema.markdown

* Update schema.markdown

* Update schema.markdown

* Update schema.markdown

* Update schema.markdown

* Update source/_docs/blueprint/schema.markdown

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
---
 source/_docs/blueprint/schema.markdown | 120 +++++++++++++++++++------
 1 file changed, 95 insertions(+), 25 deletions(-)

diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown
index c615423da5b..42c35e1a0a7 100644
--- a/source/_docs/blueprint/schema.markdown
+++ b/source/_docs/blueprint/schema.markdown
@@ -79,34 +79,12 @@ homeassistant:
       required: false
 input:
   description: >
-    A dictionary of defined user inputs. These are the input fields that the
+    A dictionary of defined user inputs or sections. These are the input fields that the
     consumer of your blueprint can provide using YAML definition, or via
-    a configuration form in the UI.
+    a configuration form in the UI. Sections provide a way to visually group a set of 
+    related inputs (see below).
   type: map
   required: false
-  keys:
-    name:
-      description: The name of the input field.
-      type: string
-      required: false
-    description:
-      description: >
-        A short description of the input field. Keep this short and descriptive.
-        The description can include [Markdown](https://commonmark.org/help/).
-      type: string
-      required: false
-    selector:
-      description: >
-        The [selector](/docs/blueprint/selectors/) to use for this input. A
-        selector defines how the input is displayed in the frontend UI.
-      type: selector
-      required: false
-    default:
-      description: >
-        The default value of this input, in case the input is not provided
-        by the user of this blueprint.
-      type: any
-      required: false
 {% endconfiguration %}
 
 ### Blueprint inputs
@@ -118,6 +96,34 @@ These inputs can be of any type (string, boolean, list, dictionary). They can ha
 a default value and also provide a [selector](/docs/blueprint/selectors/) that
 ensures a matching input field in the user interface.
 
+A blueprint input has the following configuration:
+
+{% configuration %}
+  name:
+    description: The name of the input field.
+    type: string
+    required: false
+  description:
+    description: >
+      A short description of the input field. Keep this short and descriptive.
+      The description can include [Markdown](https://commonmark.org/help/).
+    type: string
+    required: false
+  selector:
+    description: >
+      The [selector](/docs/blueprint/selectors/) to use for this input. A
+      selector defines how the input is displayed in the frontend UI.
+    type: selector
+    required: false
+  default:
+    description: >
+      The default value of this input, in case the input is not provided
+      by the user of this blueprint.
+    type: any
+    required: false
+
+{% endconfiguration %}
+
 Each input field can be referred to, outside of the blueprint metadata, using
 the `!input` custom YAML tag.
 
@@ -140,6 +146,70 @@ It is then up to the user to find out what to enter there. Blueprints that come
 
 A blueprint can have as many inputs as you like.
 
+### Blueprint input sections
+
+One or more input sections can be added under the main `input` key. Each section visually groups the inputs in that section, 
+allows an optional description, and optionally allows for collapsing those inputs. 
+
+A section is differentiated from an input by the presence of an additional `input` key within that section. 
+
+<div class='note warning'>
+Input sections are a new feature in version 2024.6. Set the `min_version` for the blueprint to at least this version if using input sections. Otherwise, the blueprint will generate errors on older versions. 
+</div>
+
+The full configuration for a section is below:
+
+{% configuration %}
+
+name:
+  description: A name for the section. If omitted the key of the section is used.
+  type: string
+  required: false
+icon:
+  description: An icon to display next to the name of the section.
+  type: string
+  required: false
+description:
+  description: >
+    An optional description of this section, which will be displayed at the top of the section.
+    The description can include [Markdown](https://commonmark.org/help/).
+  type: string
+  required: false
+collapsed:
+  description: If `true`, the section will be collapsed by default. Useful for optional or less important inputs. All collapsed inputs must also have a defined `default` before they can be hidden.
+  type: boolean
+  default: false
+  required: false
+input:
+  description: >
+    A dictionary of defined user inputs within this section.
+  type: map
+  required: true
+
+{% endconfiguration %}
+
+
+
+The following example shows a blueprint with some inputs in a section:
+
+```yaml
+blueprint:
+  name: Example sections blueprint
+  description: Example showing a section
+  input:
+    base_input:
+      name: An input not in the section
+    my_section:
+      name: My Section
+      icon: mdi:cog
+      description: These options control a specific feature of this blueprint
+      input:
+        my_input:
+          name: Example input
+        my_input_2:
+          name: 2nd example input
+```
+
 ### Blueprint inputs in templates
 
 The inputs are available as custom YAML tags, but not as template variables.