The Stateful (DOM) Elements Library is an advanced JavaScript library designed to significantly enhance the Document Object Model (DOM) by seamlessly integrating state management capabilities directly into DOM elements. By doing so, it offers developers an exceptionally convenient and efficient method for managing the state of DOM elements, thereby substantially improving code organization, readability, and maintainability. This library stands as a pivotal tool for developers seeking to streamline their web development processes and ensure a more structured and intuitive handling of dynamic content and user interactions.
You can install the Stateful DOM Elements Library via npm:
npm install stateful-dom-elementsAlternatively, you can include the library directly in your HTML file using a script tag:
<script src="stateful-dom-elements.js"></script>The setState method is used to update the custom states associated with a DOM element.
elementInternals.setState(stateName, value);stateName: A string representing the name of the custom state to be updated.value: The new value of the custom state.
stateName: (Required) A string representing the name of the custom state to be updated.value: (Required) The new value of the custom state.
- None.
// Update the custom state 'active' to true
elementInternals.setState('active', true);// Update the custom state 'error' to false
elementInternals.setState('error', false);// Update multiple custom states at once
elementInternals.setState({
'loading': true,
'visible': false
});The getState method is used to retrieve the current value of a custom state associated with a DOM element.
elementInternals.getState(stateName);stateName: A string representing the name of the custom state to retrieve.
stateName: (Required) A string representing the name of the custom state to retrieve.
- Returns the current value of the specified custom state.
// Retrieve the current value of the custom state 'active'
const isActive = elementInternals.getState('active');
console.log(isActive); // Output: true// Retrieve the current value of the custom state 'error'
const isError = elementInternals.getState('error');
console.log(isError); // Output: falseThe watchState method (or event listener) allows developers to monitor changes to a specific custom state associated with a DOM element.
element.watchState(stateName, callback);stateName: A string representing the name of the custom state to monitor.callback: A function to be executed when the specified custom state changes.
stateName: (Required) A string representing the name of the custom state to monitor.callback: (Required) A function to be executed when the specified custom state changes. This function receives an event object as its argument, which contains information about the state change.
// Watch for changes to the custom state 'active'
element.watchState('active', (event) => {
console.log('Active state changed:', event.detail.state);
});To ensure compatibility with browsers that do not support certain features, the Stateful DOM Elements Library includes polyfills for essential state management functionality:
addState:Adds a custom state to the set of states associated with a DOM element.hasState:Checks if a custom state exists in the set of states associated with a DOM element.deleteState:Removes a custom state from the set of states associated with a DOM element.
These polyfills ensure that essential state management functionality is available across a wide range of browsers, providing a consistent experience for users regardless of their browser choice.
The addState polyfill is used to add a custom state to the set of states associated with a DOM element.
elementInternals.addState(stateName);stateName: A string representing the name of the custom state to be added.
stateName: (Required) A string representing the name of the custom state to be added.
- None.
// Add the custom state 'active'
elementInternals.addState('active');The hasState polyfill is used to check if a custom state exists in the set of states associated with a DOM element.
elementInternals.hasState(stateName);stateName: A string representing the name of the custom state to check.
stateName: (Required) A string representing the name of the custom state to check.
- Returns a boolean indicating whether the specified custom state exists.
// Check if the custom state 'active' exists
const isActive = elementInternals.hasState('active');
console.log(isActive); // Output: trueThe deleteState polyfill is used to remove a custom state from the set of states associated with a DOM element.
elementInternals.deleteState(stateName);stateName: A string representing the name of the custom state to be removed.
stateName: (Required) A string representing the name of the custom state to be removed.
- None.
// Remove the custom state 'active'
elementInternals.deleteState('active');These polyfills ensure that essential state management functionality is available across a wide range of browsers, providing a consistent experience for users regardless of their browser choice.
For detailed documentation and examples, refer to the API Reference and Usage Guide provided in the repository.
Contributions to the Stateful DOM Elements Library are welcome! Please refer to the contribution guidelines for more information.
This library is licensed under the MIT License. Feel free to use, modify, and distribute it as per the terms of the license.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.EOT