@aurodesignsystem-dev/auro-formkit 0.0.0-pr1457.0 → 0.0.0-pr1457.2

package/components/form/demo/index.md

@@ -1,99 +1,66 @@
-<!--
-The index.md file is a compiled document. No edits should be made directly to this file.
-
-index.md is created by running `npm run build:markdownDocs`.
-
-This file is generated based on a template fetched from `./docs/partials/index.md`
--->
-
-# Form
-
+<auro-header level="1" id="overview">Form</auro-header>
+<div class="contentWrapper">
+<nav>
+<auro-nav anchorNavContent=".scrollWrapper">
+<span slot="mobileToggleCollapsed">View More</span>
+<span slot="mobileToggleExpanded">View Less</span>
+<auro-anchorlink fluid href="#description">Description</auro-anchorlink>
+<auro-anchorlink fluid href="#formValueGeneration">Form Value Generation</auro-anchorlink>
+<auro-anchorlink fluid href="#formDataStructure" class="level2 body-xs">Form Data Structure</auro-anchorlink>
+<auro-anchorlink fluid href="#accessingFormData">Accessing Form Data</auro-anchorlink>
+<auro-anchorlink fluid href="#basicExample">Basic Form Example</auro-anchorlink>
+</auro-nav>
+</nav>
+<div class="mainContent">
+<div class="scrollWrapper">
+<section>
+<auro-header level="2" id="description">Description</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
 <!-- The below content is automatically added from ./../docs/partials/description.md -->
-`<auro-form>` is a [HTML custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) designed to
-serve as the base logic for all auro-constructed forms.
-
-It automatically "scrapes" its inner content for any auro form elements, and surfaces
-them (along with events) to the parent form element as a JSON object.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-## Form Value Generation
-
-Auro form exists to make a developer's life easier through surfacing all Auro form elements in a given form as a single
-JSON object.
-The most common use case the Auro team identified when building Form was the need to collect form data in
-a structured way.
-
-The following is required on each Auro form element in a form for it to be collected automatically:
-
-1. It **must** have a `name` attribute. This is required if vanilla HTML forms, and we follow the same pattern.
-2. It **must** be an Auro form element. See the section on custom elements for more information.
-
-That being said, we do _not_ require form elements to be direct children of `auro-form`.
-They can be nested within other elements for styling, such as a `div`, `span` or `fieldset`.
-
-### Form Data Structure
-
-In a correctly registered scenario, `auro-form`
-will automatically recognize the auro form elements and collect data from each on the form's `value` key as a JSON object.
-
-Each element will be added using the element's `name` attribute as the key, and the element's `value` as the value.
-
-A real-world example of this might be:
-
-<pre class="language-json"><code class="language-json">{
-  "hotelCity": "New York",
-  "dates": ["2022-01-01", "2022-01-15"],
-  "numberOfGuests": 2
-}</code></pre>
-
-If your project uses TypeScript, consider using a type like this to represent the form data:
-
-<pre class="language-typescript"><code class="language-typescript">// Generic type for form values
-type AuroFormValue&lt;T&gt; = T | null;
-​
-// Example types
-type AuroInputValue = AuroFormValue&lt;string | number&gt;;
-type AuroDatePickerValue = AuroFormValue&lt;string[]&gt;;
-​
-// This is the type returned from the `AuroForm.value` getter
-interface AuroFormState {
-  // value varies based on form element
-  hotelCity: AuroInputValue;
-  dates: AuroDatePickerValue;
-  numberOfGuests: AuroInputValue;
-}</code></pre>
+<code>&lt;auro-form&gt;</code> is a <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements" target="_blank">HTML custom element</auro-hyperlink> designed to
+        serve as the base logic for all auro-constructed forms.
 
-## Accessing Form Data
-
-As Auro components are designed to be framework-agnostic, data can be retrieved using simple vanilla JavaScript patterns.
-If you have ever worked with a standard HTML5 form, you are already equipped to work with Auro forms!
-
-Once you have a reference to the form element (React ref, querySelector, etc.),
-you can access the form data using the following methods:
-
-**Data Keys + Get Methods**:
-- `.value` - Getter which returns the current form data as a JSON object.
-- `.validity` - Returns the current validity state of the form (`valid` or `invalid`).
-
-**Extra Information**:
-- `.isInitialState` - Returns a boolean indicating if the form is in its initial state.
-
-**Events**
-- `input` - Fires when the form state changes.
-- `reset` - Fires when the form is reset.
-- `submit` - Fires when the form is submitted.
-
-**Advanced Features**:
-- `.formState` - This is the internal form state. It includes extra `required` and `validity` information for each form element.
-This key is not required for normal form usage, but can add additional context for more complex forms.
-
-### Basic Form Example
-
-The most basic form implementation requires an `auro-input` and an optional auro button with `type="submit"`.
-
-By default, Auro Form connects a `submit` event to all `type="submit"` buttons within the form.
-
+        It automatically "scrapes" its inner content for any auro form elements, and surfaces
+        them (along with events) to the parent form element as a JSON object.
+<!-- AURO-GENERATED-CONTENT:END -->
+</section>
+<section>
+<auro-header level="2" id="formValueGeneration">Form Value Generation</auro-header>
+<p>Auro form exists to make a developer's life easier through surfacing all Auro form elements in a given form as a single JSON object. The most common use case the Auro team identified when building Form was the need to collect form data in a structured way.</p>
+<p>The following is required on each Auro form element in a form for it to be collected automatically:</p>
+<ol>
+<li>It <strong>must</strong> have a <code>name</code> attribute. This is required in vanilla HTML forms, and we follow the same pattern.</li>
+<li>It <strong>must</strong> be an Auro form element. See the section on custom elements for more information.</li>
+</ol>
+<p>That being said, we do <em>not</em> require form elements to be direct children of <code>auro-form</code>. They can be nested within other elements for styling, such as a <code>div</code>, <code>span</code> or <code>fieldset</code>.</p>
+<auro-header level="3" id="formDataStructure">Form Data Structure</auro-header>
+<p>In a correctly registered scenario, <code>auro-form</code> will automatically recognize the auro form elements and collect data from each on the form's <code>value</code> key as a JSON object.</p>
+<p>Each element will be added using the element's <code>name</code> attribute as the key, and the element's <code>value</code> as the value.</p>
+</section>
+<section>
+<auro-header level="2" id="accessingFormData">Accessing Form Data</auro-header>
+<p>As Auro components are designed to be framework-agnostic, data can be retrieved using simple vanilla JavaScript patterns. If you have ever worked with a standard HTML5 form, you are already equipped to work with Auro forms!</p>
+<p>Once you have a reference to the form element (React ref, querySelector, etc.), you can access the form data using the following methods:</p>
+<p><strong>Data Keys + Get Methods</strong>:</p>
+<ul>
+<li><code>.value</code> - Getter which returns the current form data as a JSON object.</li>
+<li><code>.validity</code> - Returns the current validity state of the form (<code>valid</code> or <code>invalid</code>).</li>
+</ul>
+<p><strong>Extra Information</strong>:</p>
+<ul>
+<li><code>.isInitialState</code> - Returns a boolean indicating if the form is in its initial state.</li>
+</ul>
+<p><strong>Events</strong>:</p>
+<ul>
+<li><code>input</code> - Fires when the form state changes.</li>
+<li><code>reset</code> - Fires when the form is reset.</li>
+<li><code>submit</code> - Fires when the form is submitted.</li>
+</ul>
+</section>
+<section>
+<auro-header level="2" id="basicExample">Basic Form Example</auro-header>
+<p>The most basic form implementation requires an <code>auro-input</code> and an optional auro button with <code>type="submit"</code>.</p>
+<p>By default, Auro Form connects a <code>submit</code> event to all <code>type="submit"</code> buttons within the form.</p>
 <div class="exampleWrapper">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
 <!-- The below content is automatically added from ./../apiExamples/basic.html -->
@@ -105,18 +72,21 @@ By default, Auro Form connects a `submit` event to all `type="submit"` buttons w
 <auro-button type="submit">Submit</auro-button>
 </auro-form>
 <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
 <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
-
+<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
 <pre class="language-html"><code class="language-html">&lt;auro-form&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;br /&gt;
   &lt;auro-button type="submit"&gt;Submit&lt;/auro-button&gt;
-&lt;/auro-form&gt;</code></pre>
+&lt;/auro-form&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
+</section>
+</div>
+</div>
+</div>