@aurodesignsystem-dev/auro-formkit 0.0.0-pr1471.4 → 0.0.0-pr1474.1

package/components/form/demo/customize.md

@@ -7,6 +7,8 @@
 <auro-anchorlink fluid href="#layout">Layout</auro-anchorlink>
 <auro-anchorlink fluid href="#columnLayout" class="level2 body-xs">Column Layout</auro-anchorlink>
 <auro-anchorlink fluid href="#complexForm" class="level2 body-xs">Complex Form</auro-anchorlink>
+<auro-anchorlink fluid href="#fieldState">Field State</auro-anchorlink>
+<auro-anchorlink fluid href="#disabledFields" class="level2 body-xs">Disabled Fields</auro-anchorlink>
 </auro-nav>
 </nav>
 <div class="mainContent">
@@ -24,16 +26,14 @@
             display: grid;
             grid-template-columns: 1fr 1fr;
             gap: 1rem;
+            align-items: start;
           }
 
-          .columned-form div {
-            display: flex;
-            flex-direction: column;
-            padding: 1rem;
-            gap: 1rem;
+          .columned-form .span-2 {
+            grid-column: span 2;
           }
 
-          .controls {
+          .columned-form-controls {
             display: flex;
             justify-content: flex-end;
             margin-top: 1rem;
@@ -41,29 +41,25 @@
 </style>
 <auro-form>
 <div class="columned-form">
-<div>
-<auro-input id="search-box" name="searchBox" required>
-<span slot="label">Search flights</span>
+<auro-input id="cl-first-name" name="firstName" required>
+<span slot="label">First Name</span>
 </auro-input>
-<auro-input id="last-name" name="lastName" required>
+<auro-input id="cl-last-name" name="lastName" required>
 <span slot="label">Last Name</span>
-</auro-input>
-</div>
-<div>
-<div class="datepickerBlock">
-<h4>Pick a date range</h4>
-<auro-datepicker id="date-range" name="dateRange" required range>
-<span slot="fromLabel">Start</span>
-<span slot="toLabel">End</span>
-<span slot="bib.fullscreen.fromLabel">Start</span>
-<span slot="bib.fullscreen.toLabel">End</span>
+</auro-input>
+<auro-input id="cl-email" name="email" type="email" class="span-2" required>
+<span slot="label">Email</span>
+</auro-input>
+<auro-datepicker id="cl-date-range" name="dateRange" class="span-2" required range>
+<span slot="fromLabel">Departure</span>
+<span slot="toLabel">Return</span>
+<span slot="bib.fullscreen.fromLabel">Departure</span>
+<span slot="bib.fullscreen.toLabel">Return</span>
 </auro-datepicker>
 </div>
-<div class="controls">
+<div class="columned-form-controls">
 <auro-button type="submit">Submit</auro-button>
 </div>
-</div>
-</div>
 </auro-form>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
@@ -76,16 +72,14 @@
     display: grid;
     grid-template-columns: 1fr 1fr;
     gap: 1rem;
+    align-items: start;
   }
 ​
-  .columned-form div {
-    display: flex;
-    flex-direction: column;
-    padding: 1rem;
-    gap: 1rem;
+  .columned-form .span-2 {
+    grid-column: span 2;
   }
 ​
-  .controls {
+  .columned-form-controls {
     display: flex;
     justify-content: flex-end;
     margin-top: 1rem;
@@ -93,28 +87,24 @@
 &lt;/style&gt;
 &lt;auro-form&gt;
   &lt;div class="columned-form"&gt;
-    &lt;div&gt;
-      &lt;auro-input id="search-box" name="searchBox" required&gt;
-        &lt;span slot="label"&gt;Search flights&lt;/span&gt;
-      &lt;/auro-input&gt;
-      &lt;auro-input id="last-name" name="lastName" required&gt;
-        &lt;span slot="label"&gt;Last Name&lt;/span&gt;
-      &lt;/auro-input&gt;
-    &lt;/div&gt;
-    &lt;div&gt;
-      &lt;div class="datepickerBlock"&gt;
-        &lt;h4&gt;Pick a date range&lt;/h4&gt;
-        &lt;auro-datepicker id="date-range" name="dateRange" required range&gt;
-          &lt;span slot="fromLabel"&gt;Start&lt;/span&gt;
-          &lt;span slot="toLabel"&gt;End&lt;/span&gt;
-          &lt;span slot="bib.fullscreen.fromLabel"&gt;Start&lt;/span&gt;
-          &lt;span slot="bib.fullscreen.toLabel"&gt;End&lt;/span&gt;
-        &lt;/auro-datepicker&gt;
-      &lt;/div&gt;
-      &lt;div class="controls"&gt;
-        &lt;auro-button type="submit"&gt;Submit&lt;/auro-button&gt;
-      &lt;/div&gt;
-    &lt;/div&gt;
+    &lt;auro-input id="cl-first-name" name="firstName" required&gt;
+      &lt;span slot="label"&gt;First Name&lt;/span&gt;
+    &lt;/auro-input&gt;
+    &lt;auro-input id="cl-last-name" name="lastName" required&gt;
+      &lt;span slot="label"&gt;Last Name&lt;/span&gt;
+    &lt;/auro-input&gt;
+    &lt;auro-input id="cl-email" name="email" type="email" class="span-2" required&gt;
+      &lt;span slot="label"&gt;Email&lt;/span&gt;
+    &lt;/auro-input&gt;
+    &lt;auro-datepicker id="cl-date-range" name="dateRange" class="span-2" required range&gt;
+      &lt;span slot="fromLabel"&gt;Departure&lt;/span&gt;
+      &lt;span slot="toLabel"&gt;Return&lt;/span&gt;
+      &lt;span slot="bib.fullscreen.fromLabel"&gt;Departure&lt;/span&gt;
+      &lt;span slot="bib.fullscreen.toLabel"&gt;Return&lt;/span&gt;
+    &lt;/auro-datepicker&gt;
+  &lt;/div&gt;
+  &lt;div class="columned-form-controls"&gt;
+    &lt;auro-button type="submit"&gt;Submit&lt;/auro-button&gt;
   &lt;/div&gt;
 &lt;/auro-form&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
@@ -241,6 +231,90 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 </section>
+<section>
+<auro-header level="2" id="fieldState">Field State</auro-header>
+<p>Per the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled">HTML spec</a>, form controls with the <code>disabled</code> attribute are excluded from form submission and are not validated. <code>auro-form</code> mirrors that behavior.</p>
+<auro-header level="3" id="disabledFields">Disabled Fields</auro-header>
+<p>When a child form element has the <code>disabled</code> attribute:</p>
+<ul>
+<li>Its <code>name</code> is omitted from <code>form.value</code> and from the <code>submit</code> event's <code>detail.value</code>, even if the element carries a value.</li>
+<li>It does not contribute to <code>validity</code> — a disabled <code>required</code> field will not block submission.</li>
+<li>It does not taint <code>isInitialState</code> — a disabled field carrying a preset value still leaves the form in its initial state.</li>
+</ul>
+<p><strong>Behavior change:</strong> a form whose only invalid field was a <code>disabled</code> AND <code>required</code> field is now submittable, where previously it would have been blocked. If your application relied on a <code>disabled</code>/<code>required</code> field gating submission, surface that constraint a different way (for example, only render the field once the prerequisite is met).</p>
+<p>In the example below the Mileage Plan number is preset and disabled. Fill in the remaining required fields and submit the form — the output region below the form will show the contents of the <code>submit</code> event's <code>detail.value</code>. Notice that only <code>firstName</code> and <code>lastName</code> appear; <code>loyaltyNumber</code> is omitted even though the field has a value.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
+<!-- The below content is automatically added from ./../apiExamples/disabled.html -->
+<auro-form id="disabledExampleForm">
+<auro-input id="first-name" name="firstName" required>
+<span slot="label">First Name</span>
+</auro-input>
+<br />
+<auro-input id="last-name" name="lastName" required>
+<span slot="label">Last Name</span>
+</auro-input>
+<br />
+<auro-input id="loyalty-number" name="loyaltyNumber" value="AS-123456" disabled>
+<span slot="label">Mileage Plan number</span>
+<span slot="helpText">Account number is read-only and is not submitted with the form.</span>
+</auro-input>
+<br />
+<auro-button type="submit">Submit</auro-button>
+</auro-form>
+<output id="disabledExampleOutput" form="disabledExampleForm" aria-live="polite">Submit the form to see what data gets stored.</output>
+<style>
+          #disabledExampleOutput {
+            display: block;
+            margin-top: 2rem;
+            padding: 1rem 1.25rem;
+            border-left: 4px solid #2a2a2a;
+            border-radius: 0.25rem;
+            background: #f5f5f5;
+            font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+            font-size: 0.875rem;
+            white-space: pre-wrap;
+          }
+</style>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/disabled.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-form id="disabledExampleForm"&gt;
+  &lt;auro-input id="first-name" name="firstName" required&gt;
+    &lt;span slot="label"&gt;First Name&lt;/span&gt;
+  &lt;/auro-input&gt;
+  &lt;br /&gt;
+  &lt;auro-input id="last-name" name="lastName" required&gt;
+    &lt;span slot="label"&gt;Last Name&lt;/span&gt;
+  &lt;/auro-input&gt;
+  &lt;br /&gt;
+  &lt;auro-input id="loyalty-number" name="loyaltyNumber" value="AS-123456" disabled&gt;
+    &lt;span slot="label"&gt;Mileage Plan number&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Account number is read-only and is not submitted with the form.&lt;/span&gt;
+  &lt;/auro-input&gt;
+  &lt;br /&gt;
+  &lt;auro-button type="submit"&gt;Submit&lt;/auro-button&gt;
+&lt;/auro-form&gt;
+&lt;output id="disabledExampleOutput" form="disabledExampleForm" aria-live="polite"&gt;Submit the form to see what data gets stored.&lt;/output&gt;
+&lt;style&gt;
+  #disabledExampleOutput {
+    display: block;
+    margin-top: 2rem;
+    padding: 1rem 1.25rem;
+    border-left: 4px solid #2a2a2a;
+    border-radius: 0.25rem;
+    background: #f5f5f5;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    font-size: 0.875rem;
+    white-space: pre-wrap;
+  }
+&lt;/style&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+</section>
 </div>
 </div>
 </div>