@aurodesignsystem-dev/auro-formkit 0.0.0-pr1451.20 → 0.0.0-pr1451.21

package/components/form/demo/getting-started.md

@@ -0,0 +1,291 @@
+<auro-header level="1" id="overview">Form - Getting Started</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="#setup">Setup</auro-anchorlink>
+<auro-anchorlink fluid href="#recommendedSetup" class="level2 body-xs" onclick="openAccordion('recommendedAccordion')">Recommended</auro-anchorlink>
+<auro-anchorlink fluid href="#autoSetup" class="level2 body-xs" onclick="openAccordion('autoAccordion')">Auto</auro-anchorlink>
+<auro-anchorlink fluid href="#cdnSetup" class="level2 body-xs" onclick="openAccordion('cdnAccordion')">CDN</auro-anchorlink>
+<auro-anchorlink fluid href="#minimalConfig">Minimal Configuration</auro-anchorlink>
+<auro-anchorlink fluid href="#slots">Slots</auro-anchorlink>
+<auro-anchorlink fluid href="#functions">Functions</auro-anchorlink>
+<auro-anchorlink fluid href="#fnSubmit" class="level2 body-xs">submit()</auro-anchorlink>
+<auro-anchorlink fluid href="#fnReset" class="level2 body-xs">reset()</auro-anchorlink>
+</auro-nav>
+</nav>
+<div class="mainContent">
+<div class="scrollWrapper">
+<section>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/install.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/install.md -->
+<auro-header level="2" id="setup">Setup</auro-header>
+<auro-accordion-group Emphasis>
+<auro-accordion expanded class="section" id="recommendedAccordion">
+<span slot="trigger">Recommended Installation and Implementation</span>
+<div class="accordion-content">
+<auro-header level="3">Install</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ./../../../docs/templates/componentInstall.md -->
+
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-formkit</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="3">Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/customRegistration.md -->
+
+## Custom Component Registration for Version Management
+
+There are two key parts to every Auro component: the <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes" target="_blank">class</auro-hyperlink> and the custom element definition. The class defines the component's behavior, while the custom element registers it under a specific name so it can be used in HTML.
+
+You can do this by importing only the component class and using the <code>register(name)</code> method with a unique name:
+
+<pre class="language-js"><code class="language-js">// Import the class only
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+​
+// Register with a custom name if desired
+AuroForm.register('[custom]-form');</code></pre>
+
+This will create a new custom element `<custom-form>` that behaves exactly like `<auro-form>`, allowing both to coexist on the same page without interfering with each other.
+
+### Using Custom-Named Child Form Elements
+
+When consuming custom-named Auro form elements (like `auro-input` registered as `custom-input`),
+these elements _must_ be registered BEFORE auro-form due to rendering order limitations.
+Auro form elements are automatically recognized based on their tag name (e.g. `auro-input`) or special auro attributes which are only assigned during the initial render.
+
+For example, the following is correct:
+
+<pre class="language-javascript"><code class="language-javascript">import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+​
+AuroInput.register('[custom]-input'); // adds an internal identifier auro-form uses to recognize the custom element
+AuroForm.register('[custom]-form'); // render looks for said identifier</code></pre>
+
+The following is NOT correct and will result in forms not working as expected:
+
+<pre class="language-javascript"><code class="language-javascript">import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+​
+AuroForm.register('[custom]-form'); // forms start rendering, looking for auro inputs, or custom-named inputs
+AuroInput.register('[custom]-input'); // too late, form has already rendered and did not find the custom element</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+<auro-accordion class="section" id="autoAccordion">
+<span slot="trigger">Auto Installation and Implementation</span>
+<div class="accordion-content">
+<p class="warning"><strong>Warning:</strong> Default registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.</p>
+<auro-header level="3">Install</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ./../../../docs/templates/componentInstall.md -->
+
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-formkit</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="3">Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/defaultRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/defaultRegistration.md -->
+Import the component, then register the custom element:
+
+<pre class="language-js"><code class="language-js">import '@aurodesignsystem/auro-formkit/auro-form';</code></pre>
+
+Then use the element in your HTML:
+
+<pre class="language-html"><code class="language-html">&lt;auro-form&gt;
+  &lt;auro-input 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>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+<auro-accordion class="section" id="cdnAccordion">
+<span slot="trigger">CDN Installation and Implementation</span>
+<div class="accordion-content">
+<p class="warning"><strong>Warning:</strong> CDN install & registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.</p>
+<auro-header level="3">Install & Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/cdnRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/cdnRegistration.md -->
+<p>Add the following script tag to your HTML to load the component directly from a CDN:</p>
+
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-form/+esm"&gt;&lt;/script&gt;</code></pre>
+<p>This script registers the <code>&lt;auro-form&gt;</code> custom element globally. You can then use it in your HTML:</p>
+
+<pre class="language-html"><code class="language-html">&lt;auro-form&gt;
+  &lt;auro-input 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>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+</auro-accordion-group>
+<!-- AURO-GENERATED-CONTENT:END -->
+</section>
+<section>
+<auro-header level="2" id="minimalConfig">Minimal Configuration</auro-header>
+<p>The most basic use of <code>auro-form</code> requires one or more named Auro form elements inside the form. Add a button with <code>type="submit"</code> to trigger form submission.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
+<!-- The below content is automatically added from ./../apiExamples/basic.html -->
+<auro-form>
+<auro-input id="search-box" name="searchBox" required>
+<span slot="label">Search flights</span>
+</auro-input>
+<br />
+<auro-button type="submit">Submit</auro-button>
+</auro-form>
+<!-- AURO-GENERATED-CONTENT:END -->
+</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 -->
+<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>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+</section>
+<section>
+<auro-header level="2" id="slots">Slots</auro-header>
+<p>The <code>default</code> slot accepts any Auro form elements (e.g., <code>auro-input</code>, <code>auro-select</code>, <code>auro-datepicker</code>, <code>auro-counter-group</code>) as well as any HTML elements for layout and structure.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/complex.html) -->
+<!-- The below content is automatically added from ./../apiExamples/complex.html -->
+<style>
+.submitBlock {
+margin-top: 1rem;
+display: flex;
+justify-content: flex-end;
+gap: 1rem;
+}
+.datepickerBlock {
+margin-top: 1rem;
+}
+.complex-form {
+display: block;
+padding: 1rem;
+border: 1px solid #2a2a2a;
+border-radius: 1rem;
+}
+</style>
+<auro-form class="complex-form">
+<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="occupation" name="occupation" required>
+<span slot="label">Occupation</span>
+</auro-input>
+<br />
+<auro-input-two id="cool-fact" name="coolFact" required>
+<span slot="label">Cool Fact</span>
+</auro-input-two>
+<div class="datepickerBlock">
+<h4>Pick a cool date</h4>
+<auro-datepicker id="date-example" name="dateExample" required>
+<span slot="fromLabel">Choose a date</span>
+<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+</auro-datepicker>
+</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-datepicker>
+</div>
+<div class="submitBlock">
+<auro-button type="reset">Reset</auro-button>
+<auro-button type="submit">Submit</auro-button>
+</div>
+</auro-form>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/complex.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/complex.html -->
+<pre class="language-html"><code class="language-html">&lt;style&gt;
+  .submitBlock {
+    margin-top: 1rem;
+    display: flex;
+    justify-content: flex-end;
+    gap: 1rem;
+  }
+  .datepickerBlock {
+    margin-top: 1rem;
+  }
+  .complex-form {
+    display: block;
+    padding: 1rem;
+    border: 1px solid #2a2a2a;
+    border-radius: 1rem;
+  }
+&lt;/style&gt;
+&lt;auro-form class="complex-form"&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="occupation" name="occupation" required&gt;
+    &lt;span slot="label"&gt;Occupation&lt;/span&gt;
+  &lt;/auro-input&gt;
+  &lt;br /&gt;
+  &lt;auro-input-two id="cool-fact" name="coolFact" required&gt;
+    &lt;span slot="label"&gt;Cool Fact&lt;/span&gt;
+  &lt;/auro-input-two&gt;
+  &lt;div class="datepickerBlock"&gt;
+    &lt;h4&gt;Pick a cool date&lt;/h4&gt;
+    &lt;auro-datepicker id="date-example" name="dateExample" required&gt;
+      &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
+      &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
+    &lt;/auro-datepicker&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="submitBlock"&gt;
+    &lt;auro-button type="reset"&gt;Reset&lt;/auro-button&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 -->
+</auro-accordion>
+</section>
+<section>
+<auro-header level="2" id="functions">Functions</auro-header>
+<auro-header level="3" id="fnSubmit">submit()</auro-header>
+<p>Validates all form elements. If all are valid, fires a <code>submit</code> event with <code>detail.value</code> containing the current form values. If any element is invalid, its error state is surfaced and the <code>submit</code> event is not fired.</p>
+<auro-header level="3" id="fnReset">reset()</auro-header>
+<p>Resets all form elements to their initial state and fires a <code>reset</code> event. The event's <code>detail.previousValue</code> contains the form values captured immediately before the reset.</p>
+</section>
+</div>
+</div>
+</div>

package/components/form/demo/index.html

@@ -18,8 +18,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Auro Web Component Demo | auro-form</title>
 
-    <!-- Prism.js Stylesheet -->
-    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"/>
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
 
     <!-- Legacy reference is still needed to support auro-form's use of legacy token values at this time -->
     <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
@@ -32,25 +32,23 @@
     
     <!-- Demo Specific Styles -->
     <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
-    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
-</head>
+    <link rel="stylesheet" type="text/css" href="./styles.css" />
+  </head>
   <body class="auro-markdown">
     <main></main>
 
     <script type="module">
-      import 'https://cdn.jsdelivr.net/npm/marked@latest/marked.min.js';
-      import 'https://cdn.jsdelivr.net/npm/prismjs@latest/prism.js';
-      fetch('./index.md')
-        .then((response) => response.text())
-        .then((text) => {
-          const rawHtml = marked.parse(text);
-          document.querySelector('main').innerHTML = rawHtml;
-          Prism.highlightAll();
-        });
+      import { renderPage } from './demo-support.js';
+      await renderPage('./index.md');
     </script>
-    <script type="module" data-demo-script="true" src="./index.min.js"></script>
 
     <!-- If additional elements are needed for the demo, add them here. -->
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-nav@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
+
+    <script src="./index.min.js" data-demo-script="true" type="module"></script>
   </body>
 </html>

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.
-
+<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.
+
 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>
-
-## 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.
-
+<!-- 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>