Merge pull request #8 from practical-computer/thomas/pract-138-prefix-all-data-attributes-to-data-pf-errors

Prefix all `data` attributes with `data-pf-` to unify + avoid collisions

Author: tcannonfodder

README.md

@@ -79,18 +79,18 @@ applyErrorMappingButton.addEventListener(`click`, (event) => {
   <custom-error-handling>
     <form id="test-form" aria-describedby='test-form-error-container'>
       <input type="email" id="email-field" aria-describedby="email-field-errors" minlength="4">
-      <section id="email-field-errors" data-error-container>
+      <section id="email-field-errors" data-pf-error-container>
         <ul>
-          <li data-visible data-error-type="error_1">ad-hoc error message 1 <small>(rendered on initial load)</small></li>
-          <li data-preserve data-error-type="tooShort">Custom Preserved Error: Must be at least 4 characters<small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-type="error_1">ad-hoc error message 1 <small>(rendered on initial load)</small></li>
+          <li data-pf-error-preserve data-pf-error-type="tooShort">Custom Preserved Error: Must be at least 4 characters<small>(rendered on initial load)</small></li>
         </ul>
       </section>
 
-      <section id="test-form-error-container" data-error-container>
+      <section id="test-form-error-container" data-pf-error-container>
         <h2>Form Errors</h2>
         <ul>
-          <li data-visible data-error-type="error_2">ad-hoc error message 2 <small>(rendered on initial load)</small></li>
-          <li data-visible data-preserve data-error-type="error_3">Preserved Error <small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-type="error_2">ad-hoc error message 2 <small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-preserve data-pf-error-type="error_3">Preserved Error <small>(rendered on initial load)</small></li>
         </ul>
       </section>
 
@@ -105,7 +105,7 @@ applyErrorMappingButton.addEventListener(`click`, (event) => {
   <textarea id="easy-console" readonly rows=20></textarea>
 
   <template id="pf-error-list-item-template">
-    <li><span>‼️</span> <span data-error-message></span></li>
+    <li><span>‼️</span> <span data-pf-error-message></span></li>
   </template>
 </body>
 ```
@@ -143,18 +143,18 @@ The following terms are used for this package:
 The following data attributes are used by this package:
 
 - Inputs
-  - Validation Event Handling flags.  This package does not provide the validations, but does provide helper functions for checks if an event handler should proceed by checking the value of `data-validation`:
-    - `data-validation="input"`: This input should use `input` validation
-    - `data-validation="change"`: This input should use `change` validation
-    - `data-validation="focusout"`: This input should use `focusout` validation
-    - `data-validation="skip"`: This input should skip any validations
-  - `data-initial-load-errors`: If present, this input has initial load errors, which should not be cleared out when reflecting the constraint validation for the initial load.
-- `data-error-container`: Marks an element as an error container
+  - Validation Event Handling flags.  This package does not provide the validations, but does provide helper functions for checks if an event handler should proceed by checking the value of `data-pf-validation`:
+    - `data-pf-validation="input"`: This input should use `input` validation
+    - `data-pf-validation="change"`: This input should use `change` validation
+    - `data-pf-validation="focusout"`: This input should use `focusout` validation
+    - `data-pf-validation="skip"`: This input should skip any validations
+  - `data-pf-initial-load-errors`: If present, this input has initial load errors, which should not be cleared out when reflecting the constraint validation for the initial load.
+- `data-pf-error-container`: Marks an element as an error container
 - Error list items
-  - `data-visible`: Marks that the error list item should be visible
-  - `data-error-type`: The error type for this list item (eg: `tooShort`, or `some_custom_error_type`)
-  - `data-preserve`: This error list item should not be removed when clearing the error list; useful for rendering custom error messages for default error types. *Just because an error is preserved does not mean it is visible*
-- `data-error-message` Used in the error list item `template` element to indicate where an error message should be rendered in the markup as the `textContent`
+  - `data-pf-error-visible`: Marks that the error list item should be visible
+  - `data-pf-error-type`: The error type for this list item (eg: `tooShort`, or `some_custom_error_type`)
+  - `data-pf-error-preserve`: This error list item should not be removed when clearing the error list; useful for rendering custom error messages for default error types. *Just because an error is preserved does not mean it is visible*
+- `data-pf-error-message` Used in the error list item `template` element to indicate where an error message should be rendered in the markup as the `textContent`
 
 ### Marking an input as invalid
 
@@ -164,20 +164,20 @@ We use `aria-invalid="true"` to indicate that an input is invalid. This makes yo
 
 To link an `input` or `form` to an error container, you:
 
-- Add the error container's markup to the page, with a unique `id` and the `data-error-container` attribute
+- Add the error container's markup to the page, with a unique `id` and the `data-pf-error-container` attribute
 - Include that `id` in the `input`/`form`'s `aria-describedby`
 
-We use the `aria-describedby` so that your markup is **accessible by default**. Since there can be [multiple elements that describe an element](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby#id_reference_list), You specify which one is the error container using `data-error-container`.
+We use the `aria-describedby` so that your markup is **accessible by default**. Since there can be [multiple elements that describe an element](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby#id_reference_list), You specify which one is the error container using `data-pf-error-container`.
 
 #### Example
 ```html
 <form id="test-form" aria-describedby='test-form-error-container'>
   <input type="email" id="email-field" aria-describedby="email-field-errors" minlength="4">
-  <section id="email-field-errors" data-error-container>
+  <section id="email-field-errors" data-pf-error-container>
     <ul></ul>
   </section>
 
-  <section id="test-form-error-container" data-error-container>
+  <section id="test-form-error-container" data-pf-error-container>
     <h2>Form Errors</h2>
     <ul></ul>
   </section>
@@ -215,14 +215,14 @@ if (!window.customElements.get('app-error-handling')) {
 
 ### Handling the initial page load
 
-- Render any error list items that should be visible on the initial page load with the `data-visible` attribute
+- Render any error list items that should be visible on the initial page load with the `data-pf-error-visible` attribute
 - Mark the invalid inputs with:
   - `aria-invalid=true` 
-  - `data-initial-load-errors`
+  - `data-pf-initial-load-errors`
 
 To reflect any other errors that might be present from the Constraint Validation API, you can use the `reflectConstraintValidationForInitialLoad` method in `@practical-computer/error-handling/element-utilities`.
 
-This method will skip any `form.elements` with blank values, or the `data-initial-load-errors` attribute.
+This method will skip any `form.elements` with blank values, or the `data-pf-initial-load-errors` attribute.
 
 
 ### Server-side errors
@@ -294,7 +294,7 @@ One of the best ways to understand this package is to glance at the source. It's
   - Any preserved errors for a list (or for a specific `type` of error)
 - Rendering helper functions, including:
   - Reflecting the current [`ValidityState`](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) of an element
-  - Applyig the `data-` and ARIA attributes to mark an element as invalid, without going through the Constraint Validation API
+  - Applyig the `data-pf` and ARIA attributes to mark an element as invalid, without going through the Constraint Validation API
   - Marking an error `type` as visible for an element
   - Creating a new error list item element
   - Clearing the error list for an element, or for an entire form.
@@ -323,7 +323,7 @@ Validation is almost always application/framework dependent; and best served by
 
 #### Markup for rendering errors
 
-You provide the markup, using ARIA attributes, a small set of `data-` attributes, and a `template` element. Fitting error messages into a design is *tough* and extremely context specific. We trust your judgement, and render the text and set the `data-visible` attributes in the places you put us to.
+You provide the markup, using ARIA attributes, a small set of `data-` attributes (prefixed with `data-pf`), and a `template` element. Fitting error messages into a design is *tough* and extremely context specific. We trust your judgement, and render the text and set the `data-pf-error-visible` attributes in the places you put us to.
 
 #### Automatic integrations/hooks/event handlers
 

css/util.css

@@ -1,7 +1,7 @@
-[data-error-container]:not(:has([data-visible])) {
+[data-pf-error-container]:not(:has([data-pf-error-visible])) {
   display: none;
 }
 
-[data-error-container] > ul > li:not([data-visible]) {
+[data-pf-error-container] > ul > li:not([data-pf-error-visible]) {
   display: none;
 }

demo/index.html

@@ -77,7 +77,7 @@
       padding: 1em;
     }
 
-    [data-error-container] {
+    [data-pf-error-container] {
       border: 1px solid red;
     }
   </style>
@@ -90,18 +90,18 @@ <h1>Practical Error Handling Demo</h1>
   <custom-error-handling>
     <form id="test-form" aria-describedby='test-form-error-container'>
       <input type="email" id="email-field" aria-describedby="email-field-errors" minlength="4">
-      <section id="email-field-errors" data-error-container>
+      <section id="email-field-errors" data-pf-error-container>
         <ul>
-          <li data-visible data-error-type="error_1">ad-hoc error message 1 <small>(rendered on initial load)</small></li>
-          <li data-preserve data-error-type="tooShort">Custom Preserved Error: Must be at least 4 characters<small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-type="error_1">ad-hoc error message 1 <small>(rendered on initial load)</small></li>
+          <li data-pf-error-preserve data-pf-error-type="tooShort">Custom Preserved Error: Must be at least 4 characters<small>(rendered on initial load)</small></li>
         </ul>
       </section>
 
-      <section id="test-form-error-container" data-error-container>
+      <section id="test-form-error-container" data-pf-error-container>
         <h2>Form Errors</h2>
         <ul>
-          <li data-visible data-error-type="error_2">ad-hoc error message 2 <small>(rendered on initial load)</small></li>
-          <li data-visible data-preserve data-error-type="error_3">Preserved Error <small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-type="error_2">ad-hoc error message 2 <small>(rendered on initial load)</small></li>
+          <li data-pf-error-visible data-pf-error-preserve data-pf-error-type="error_3">Preserved Error <small>(rendered on initial load)</small></li>
         </ul>
       </section>
 
@@ -116,7 +116,7 @@ <h2>Form Errors</h2>
   <textarea id="easy-console" readonly rows=20></textarea>
 
   <template id="pf-error-list-item-template">
-    <li><span>‼️</span> <span data-error-message></span></li>
+    <li><span>‼️</span> <span data-pf-error-message></span></li>
   </template>
 </body>
 </html>

src/element-utilities.js

@@ -11,39 +11,39 @@ export function generateValidationMessage(element) {
 }
 
 /**
- * Checks if the given `element` has `data-validation == "input"`
+ * Checks if the given `element` has `data-pf-validation == "input"`
  * @param {Element} element
- * @return {boolean} Returns true if the element does not have `data-validation == "input"`
+ * @return {boolean} Returns true if the element does not have `data-pf-validation == "input"`
  */
 export function skipInputValidation(element) {
-  return !(element.getAttribute(`data-validation`) === "input")
+  return !(element.getAttribute(`data-pf-validation`) === "input")
 }
 
 /**
- * Checks if the given `element` has `data-validation == "change"`
+ * Checks if the given `element` has `data-pf-validation == "change"`
  * @param {Element} element
- * @return {boolean} Returns true if the element does not have `data-validation == "change"`
+ * @return {boolean} Returns true if the element does not have `data-pf-validation == "change"`
  */
 export function skipChangeValidation(element) {
-  return !(element.getAttribute(`data-validation`) === "change")
+  return !(element.getAttribute(`data-pf-validation`) === "change")
 }
 
 /**
- * Checks if the given `element` has `data-validation == "focusout"`
+ * Checks if the given `element` has `data-pf-validation == "focusout"`
  * @param {Element} element
- * @return {boolean} Returns true if the element does not have `data-validation == "focusout"`
+ * @return {boolean} Returns true if the element does not have `data-pf-validation == "focusout"`
  */
 export function skipFocusoutValidation(element) {
-  return !(element.getAttribute(`data-validation`) === "focusout")
+  return !(element.getAttribute(`data-pf-validation`) === "focusout")
 }
 
 /**
- * Checks if the given `element` given `element` has `data-validation == "skip"`
+ * Checks if the given `element` given `element` has `data-pf-validation == "skip"`
  * @param {Element} element
- * @return {boolean} Returns true if the element has `data-validation == "change"`
+ * @return {boolean} Returns true if the element has `data-pf-validation == "change"`
  */
 export function skipValidation(element) {
-  return (element.getAttribute(`data-validation`) === "skip")
+  return (element.getAttribute(`data-pf-validation`) === "skip")
 }
 
 /**
@@ -74,12 +74,12 @@ export function setValidityStateAttributes(element, isValid) {
 
 /**
  * Used for the initial loading of the given `form`, calls {@link reflectConstraintValidationForElement} for each
- * non-blank item in `form.element` that does not have a `data-initial-load-errors`
+ * non-blank item in `form.element` that does not have a `data-pf-initial-load-errors`
  * @params {FormElement} form the form to reflect the initial Constraint Validation state for
  */
 export function reflectConstraintValidationForInitialLoad(form) {
   for(const element of form.elements) {
-    if(element.hasAttribute(`data-initial-load-errors`)) {
+    if(element.hasAttribute(`data-pf-initial-load-errors`)) {
       continue; // do not change any elements that have server-side errors
     }
     if(element.value !=="" ){

src/error-containers.js

@@ -3,16 +3,16 @@ import { generateValidationMessage } from './element-utilities.js'
 
 /**
  * Returns the ID for the given `element`'s `aria-describedby` attribute of the element that has a
- * `data-error-container` attribute`
+ * `data-pf-error-container` attribute`
  * @param {Element} element
- * @returns {string|undefined} the `aria-describedby` attribute if present and the element has the `data-error-container` attribute`
+ * @returns {string|undefined} the `aria-describedby` attribute if present and the element has the `data-pf-error-container` attribute`
  */
 export function getErrorContainerID(element) {
   const errorContainerID = element.getAttribute(`aria-describedby`)
   if(!errorContainerID || errorContainerID == ''){ return }
 
   return errorContainerID.split(" ").find((x) => {
-    return document.getElementById(x)?.hasAttribute(`data-error-container`)
+    return document.getElementById(x)?.hasAttribute(`data-pf-error-container`)
   })
 }
 
@@ -53,16 +53,16 @@ export function getErrorListFromContainer(container) {
 }
 
 /**
- * Returns the `NodeList` of elements inside the given `errorListElement` with `data-preserve`
+ * Returns the `NodeList` of elements inside the given `errorListElement` with `data-pf-error-preserve`
  * @param {Element} element
- * @returns {NodeList} All elements with the `data-preserve` attribute
+ * @returns {NodeList} All elements with the `data-pf-error-preserve` attribute
  */
 export function getPreservedErrors(errorListElement) {
-  return errorListElement.querySelectorAll(`:scope > [data-preserve]`)
+  return errorListElement.querySelectorAll(`:scope > [data-pf-error-preserve]`)
 }
 
 /**
- * Checks the given `errorListElement` for any preserved errors ({@link getPreservedErrors}) where the `data-error-type`
+ * Checks the given `errorListElement` for any preserved errors ({@link getPreservedErrors}) where the `data-pf-error-type`
  * matches` `type`
  * @params {Element} {@link getErrorList}
  * @params {string} type the error type
@@ -73,35 +73,35 @@ export function hasPreservedErrorForType(errorListElement, type) {
 }
 
 /**
- * Checks the given `errorListElement` for any preserved errors ({@link getPreservedErrors}) where the `data-error-type`
+ * Checks the given `errorListElement` for any preserved errors ({@link getPreservedErrors}) where the `data-pf-error-type`
  * matches` `type` and returns the first match if present
  * @params {Element} {@link getErrorList}
  * @params {string} type the error type
  * @returns {Element|null}
  */
 export function getPreservedErrorForType(errorListElement, type) {
   return [...getPreservedErrors(errorListElement)].find((x) => {
-    return x.getAttribute(`data-error-type`)?.toString() == type.toString()
+    return x.getAttribute(`data-pf-error-type`)?.toString() == type.toString()
   })
 }
 
 /**
- * Marks the given element as a preserved error message, with the `data-preserve` attribute
+ * Marks the given element as a preserved error message, with the `data-pf-error-preserve` attribute
  * @params {Element} element the error element to mark as preserved
  */
 export function markAsPreservedError(element) {
-  element.setAttribute(`data-preserve`, true)
+  element.setAttribute(`data-pf-error-preserve`, true)
 }
 
 /**
- * Returns the `element` that has the given `data-error-type` if it's present.
+ * Returns the `element` that has the given `data-pf-error-type` if it's present.
  * @params {Element} {@link getErrorList}
  * @params {string} type the error type
  * @returns {Element|null}
  */
 export function getErrorForType(errorListElement, type) {
-  return [...errorListElement.querySelectorAll(`[data-error-type]`)].find((x) => {
-    return x.getAttribute(`data-error-type`)?.toString() == type.toString()
+  return [...errorListElement.querySelectorAll(`[data-pf-error-type]`)].find((x) => {
+    return x.getAttribute(`data-pf-error-type`)?.toString() == type.toString()
   })
 }
 

src/error-mapping.js

@@ -30,7 +30,7 @@ import {
  * @param {string} errors[].container_id - The ID of the container this error message should be rendered in
  * @param {string} errors[].element_id - The ID of the element to call {@link setValidityStateAttributes} with `false` for
  * @param {string} errors[].message - the error message
- * @param {string} errors[].type - the value for `data-error-type` that represents the type of error this is
+ * @param {string} errors[].type - the value for `data-pf-error-type` that represents the type of error this is
  *
  * @example
  * // For example, a JSON response from a fetch request

src/event-handlers.js

@@ -35,7 +35,7 @@ export function validateFormSubmitEventHandler(event) {
 
 /**
  * Calls {@link reflectConstraintValidationForElement} if the `event.target` has
- * `data-validation="input"` and does not have `data-skip-validation`
+ * `data-pf-validation="input"`
  *
  * @param {Event} event
  */
@@ -48,7 +48,7 @@ export function inputValidationEventHandler(event) {
 
 /**
  * Calls {@link reflectConstraintValidationForElement} if the `event.target` has
- * `data-validation="focusout"` and does not have `data-skip-validation`
+ * `data-pf-validation="focusout"`
  * @param {Event} event
  */
 export function focusoutValidationEventHandler(event) {