npm - @aurodesignsystem/auro-formkit - Versions diffs - 2.0.0-beta.8 → 2.0.0 - Mend

@aurodesignsystem/auro-formkit 2.0.0-beta.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (968) hide show

package/components/form/demo/index.html ADDED Viewed

@@ -0,0 +1,48 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/index.md
+  With the exception of adding custom elements if needed for the demo.
+  ----------------------- DO NOT EDIT -----------------------------
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Generator | auro-form custom element</title>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"
+    />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/tokens/CSSCustomProperties.css">
+    <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>
+  <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();
+        });
+    </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/dist/auro-accordion__bundled.js" type="module"></script>
+  </body>
+</html>

package/components/form/demo/index.md CHANGED Viewed

@@ -3,38 +3,107 @@ The index.md file is a compiled document. No edits should be made directly to th
 index.md is created by running `npm run build:markdownDocs`.
-This file is generated based on a template fetched from `./docs/partials/index.md`
--->
-<!--
-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
-## Dropdown
+# Form
 <!-- 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) for the purpose of ...
+`<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.
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam convallis in tellus nec pellentesque. Integer bibendum ligula sit amet vehicula gravida. Maecenas accumsan, ligula vitae molestie iaculis, tellus mi laoreet ex [install instructions](https://auro.alaskaair.com/components/auro/button/install), ac malesuada velit dolor vel mi. Cras et rutrum urna. Sed mattis mi eu tortor ullamcorper, egestas bibendum mauris cursus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus viverra eros eget neque commodo vulputate. In tempus eu velit at dictum.
+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 data generation
-Nulla at augue facilisis `odio lobortis` molestie vitae a nulla.
-<!-- AURO-GENERATED-CONTENT:END -->
-<auro-dropdown id="testing">
-    <span slot="trigger">default 1</span>
-    <span>this should go in the default slot</span>
-</auro-dropdown>
-<br /><br /><br />
-<my-select></my-select>
-<br /><br /><br /><br />
+As covered in the description, `auro-form` makes a developer's life easier by surfacing Auro form elements as a 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 for an Auro form element 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 note below for custom elements.
+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`.
+## Important note for custom elements
+When consuming custom-named Auro form elements (like `auro-input` as `my-custom-input`), these elements _must_ be registered
+BEFORE auro-form due to rendering order and Shadown DOM limitations.
+For example, the following is correct:
+```javascript
+import {AuroInput} from '@aurodesignsystem/auro-input';
+import {AuroForm} from '@aurodesignsystem/auro-form';
+AuroInput.register('my-custom-input'); // adds an internal identifier auro-form uses to recognize the custom element
+AuroForm.register(); // render looks for said identifier
+```
+The following is NOT correct and will result in forms not working as expected:
+```javascript
+import {AuroInput} from '@aurodesignsystem/auro-input';
+import {AuroForm} from '@aurodesignsystem/auro-form';
+AuroForm.register(); // forms start rendering, looking for auro inputs, or custom-named inputs
+AuroInput.register('my-custom-input'); // too late, form has already rendered and did not find the custom element
+```
+In a correctly registered scenario, `auro-form` will automatically recognize the custom element and collect its data in the following shape:
+```typescript
+interface AuroFormState {
+  // value varies based on form element
+  [key: string]: string | string[] | number | boolean | null;
+}
+```
+A real-world example of this might be:
+```json
+{
+  "hotelCity": "New York",
+  "dates": ["2022-01-01", "2022-01-15"],
+  "numberOfGuests": 2
+}
+```
+## Examples
-## Input
+### Basic Form
+The most basic form implementation requires an `auro-input` and an optional auro button with `type="submit"`.
-<auro-input required placeholder="John Doe">
-    <span slot="label">Full name</span>
-</auro-input>
+By default, Auro Form connects a `submit` event to all `type="submit"` buttons within the form.
+<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>
+    <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 -->
+```html
+<auro-form>
+  <auro-input id="search-box" name="searchBox" required>
+    <span slot="label">Search flights</span>
+  </auro-input>
+  <auro-button type="submit">Submit</auro-button>
+</auro-form>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>