@efflore/ui-element

<!doctype html> <html> <head> <title>UIElement Docs – API Reference</title> <link rel="stylesheet" href="assets/css/global.css"> <link rel="stylesheet" href="assets/css/okaidia.css"> <link rel="stylesheet" href="assets/css/components.css"> <script type="module" src="assets/js/main.min.js"></script> </head> <body> <header class="content-grid"> <h1 class="content">UIElement Docs Version 0.8.5</h1> <nav class="breakout"> <ol> <li> <a href="index.html"> 📘 Introduction Overview and key benefits of UIElement </a> </li> <li> <a href="installation-setup.html"> ⚙️ Installation & Setup How to install and set up the library </a> </li> <li> <a href="core-concepts.html"> 🧩 Core Concepts Learn about signals, state, and reactivity </a> </li> <li> <a href="detailed-walkthrough.html"> 📋 Detailed Walkthrough Step-by-step guide to creating components </a> </li> <li> <a href="best-practices-patterns.html"> 💡 Best Practices & Patterns Tips for effective and scalable usage </a> </li> <li> <a href="advanced-topics.html"> 🚀 Advanced Topics Diving deeper into contexts and performance </a> </li> <li> <a href="examples-recipes.html"> 🧪 Examples & Recipes Sample components and practical use cases </a> </li> <li> <a href="troubleshooting-faqs.html"> ❓ Troubleshooting & FAQs Common issues and frequently asked questions </a> </li> <li class="active"> <a href="api-reference.html"> 📚 API Reference Detailed documentation of classes and methods </a> </li> <li> <a href="contributing-development.html"> 🤝 Contributing & Development How to contribute and set up the dev environment </a> </li> <li> <a href="changelog-versioning.html"> 📝 Changelog & Versioning Track changes and understand versioning </a> </li> <li> <a href="licensing-credits.html"> ⚖️ Licensing & Credits License details and acknowledgments </a> </li> </ol> </nav> </header> <main> <section class="hero"> <h1>📚 API Reference</h1> Explore the full API of UIElement, the lightweight library for creating reactive Web Components. This guide provides a detailed overview of constructors, lifecycle callbacks, state management, attribute parsing, events, auto-effects, and helper functions to help you get the most out of your components. </section>  <section> <h2>UIElement Base Class</h2> <h3>1.1 Constructor and Lifecycle Callbacks</h3>  <details> <summary>constructor(): Initializes the component</summary> The constructor initializes the instance of the `UIElement` class, extending `HTMLElement`. It is recommended to perform only simple initializations here, as the component is not yet connected to the DOM. </details>  <details> <summary>connectedCallback(): Called when the element is connected to the DOM</summary> Invoked when the custom element is inserted into the DOM. Use this lifecycle method for setting up component state, bindings, and effects. This is where you access child elements, attributes, and context. </details>  <details> <summary>disconnectedCallback(): Called when the element is removed from the DOM</summary> Triggered when the custom element is removed from the DOM. Clean up any event listeners or subscriptions added in `connectedCallback()` to avoid memory leaks. </details>  <details> <summary>attributeChangedCallback(name, oldValue, newValue): Responds to attribute changes</summary> Invoked when one of the observed attributes is added, removed, or changed. Use this method to handle changes in attributes that should trigger corresponding changes in signals or the DOM. <ul> <li><code>name</code>: The name of the changed attribute.</li> <li><code>oldValue</code>: The previous value of the attribute.</li> <li><code>newValue</code>: The new value of the attribute.</li> </ul> </details> <h3>1.2 Static Properties & Methods</h3>  <details> <summary>observedAttributes: string[]</summary> A static getter that returns an array of attribute names for the element to observe. When these attributes change, `attributeChangedCallback()` is called. </details>  <details> <summary>attributeMap: { [key: string]: (value: string | null) => any }</summary> An object defining how observed attributes are parsed into signals. The key is the attribute name, and the value is a parser function that transforms the attribute's value into an appropriate signal type. </details>  <details> <summary>providedContexts: string[]</summary> A static property that returns an array of context keys provided by the component. Contexts are state values shared between components in the same tree. </details>  <details> <summary>consumedContexts: string[]</summary> A static property that returns an array of context keys consumed by the component. When the component is connected, it requests these contexts from its ancestors. </details>  <details> <summary>define(): Registers the custom element</summary> Registers the component with a custom tag name in the `CustomElementRegistry`. It ensures that the tag name is valid and not already defined. <ul> <li><code>define(tag: string)</code>: Registers the component with the provided tag name.</li> </ul> </details> <h3>1.3 Instance Properties & Methods</h3>  <details> <summary>self: `HTMLElement`</summary> Refers to the component instance itself. It is useful for adding effects or accessing the component as a target for state synchronization. </details>  <details> <summary>root: `HTMLElement | ShadowRoot`</summary> Refers to the root of the component, which could be either the Light DOM or the Shadow DOM, depending on how the component is set up. </details>  <details> <summary>has(key): Checks if a signal exists</summary> Checks whether a signal with the specified key exists within the component's state. <ul> <li><code>key</code>: The key of the signal to check for.</li> <li>**Returns**: <code>boolean</code> - <code>true</code> if the signal exists, <code>false</code> otherwise.</li> </ul> </details>  <details> <summary>get(key): Retrieves the value of a signal</summary> Retrieves the current value of a signal within the component. <ul> <li><code>key</code>: The key of the signal to retrieve.</li> <li>**Returns**: The current value of the signal.</li> </ul> </details>  <details> <summary>set(key, value): Creates or updates a signal</summary> Sets the value of a signal within the component. The value can either be a primitive or a function that receives the old value. <ul> <li><code>key</code>: The key of the signal to set or update.</li> <li><code>value</code>: The new value for the signal, or a function that receives the old value.</li> </ul> </details>  <details> <summary>delete(key): Deletes a signal</summary> Removes the signal with the specified key from the component's state. <ul> <li><code>key</code>: The key of the signal to delete.</li> </ul> </details>  <details> <summary>signal(key, value): Initializes a new signal</summary> Initializes a new signal within the component, setting its initial value. <ul> <li><code>key</code>: The key for the new signal.</li> <li><code>value</code>: The initial value for the signal.</li> </ul> </details>  <details> <summary>first(selector): Selects the first matching child element</summary> Uses `querySelector()` to select the first child element that matches the provided selector. <ul> <li><code>selector</code>: The CSS selector to match elements.</li> <li>**Returns**: The first matching child element.</li> </ul> </details>  <details> <summary>all(selector): Selects all matching child elements</summary> Uses `querySelectorAll()` to select all child elements that match the provided selector. <ul> <li><code>selector</code>: The CSS selector to match elements.</li> <li>**Returns**: A NodeList of all matching child elements.</li> </ul> </details> </section> <section> <h2>2. Attribute Parser Functions</h2>  <details> <summary>parse(value, type): Parses a value into a specific type</summary> Converts the given string value into the appropriate type based on the provided parser function. <ul> <li><code>value</code>: The string to be parsed.</li> <li><code>type</code>: The type to convert the string to (e.g., boolean, number).</li> <li>**Returns**: The parsed value in the correct type.</li> </ul> </details>  <details> <summary>asBoolean(value): Parses a string into a boolean</summary> Converts the string value to `true` if it is not `null`, otherwise `false`. <ul> <li><code>value</code>: The string value to be parsed.</li> <li>**Returns**: `true` if the value is not `null`, `false` otherwise.</li> </ul> </details>  <details> <summary>asInteger(value): Parses a string into an integer</summary> Converts the string value into an integer. If the value is not a finite number, defaults to `0`. <ul> <li><code>value</code>: The string value to be parsed.</li> <li>**Returns**: The parsed integer value or `0` if not finite.</li> </ul> </details>  <details> <summary>asNumber(value): Parses a string into a number</summary> Converts the string value into a number. If parsing fails, returns `NaN`. <ul> <li><code>value</code>: The string value to be parsed.</li> <li>**Returns**: The parsed number or `NaN` if parsing fails.</li> </ul> </details>  <details> <summary>asString(value): Returns the value as a string</summary> Returns the value unchanged as a string. <ul> <li><code>value</code>: The string value to be returned.</li> <li>**Returns**: The original string value.</li> </ul> </details>  <details> <summary>asJSON(value): Parses a string into a JSON object</summary> Converts the string value into a JavaScript object using `JSON.parse()`. <ul> <li><code>value</code>: The string value to be parsed as JSON.</li> <li>**Returns**: The parsed JavaScript object.</li> </ul> </details> </section> <section> <h2>3. State Passing Function</h2>  <details> <summary>pass(state): Passes signals to another component</summary> Transfers one or more signals from the current component to another target component. Useful for sharing state between parent and child components. <ul> <li><code>state</code>: An object containing key-value pairs of signal names and their respective values or functions.</li> </ul> </details> </section> <section> <h2>4. Event Functions</h2>  <details> <summary>on(event, callback): Attaches an event listener</summary> Adds an event listener to the current component or a target element. The callback function is executed when the event is triggered. <ul> <li><code>event</code>: The name of the event to listen for (e.g., `click`, `input`).</li> <li><code>callback</code>: The function to execute when the event is triggered.</li> </ul> </details>  <details> <summary>off(event, callback): Removes an event listener</summary> Removes an event listener from the current component or a target element. <ul> <li><code>event</code>: The name of the event to stop listening for.</li> <li><code>callback</code>: The function that was originally passed to `on()`.</li> </ul> </details>  <details> <summary>emit(event, detail): Dispatches a custom event</summary> Creates and dispatches a custom event from the component. Useful for communicating state changes to parent components or triggering custom event handlers. <ul> <li><code>event</code>: The name of the event to dispatch.</li> <li><code>detail</code>: An object containing data to pass with the event.</li> </ul> </details> </section> <section> <h2>5. Auto-Effect Functions</h2>  <details> <summary>setText(signal): Synchronizes text content with a signal</summary> Binds a signal to the text content of an element within the component. Automatically updates the text when the signal changes. <ul> <li><code>signal</code>: The signal key or function to bind to the text content.</li> </ul> </details>  <details> <summary>setProperty(name, signal): Synchronizes a property with a signal</summary> Binds a signal to a property on the component, automatically updating the property whenever the signal changes. <ul> <li><code>name</code>: The name of the property to bind.</li> <li><code>signal</code>: The signal key or function to bind to the property.</li> </ul> </details>  <details> <summary>setAttribute(name, signal): Synchronizes an attribute with a signal</summary> Binds a signal to an attribute on the component, updating the attribute whenever the signal changes. <ul> <li><code>name</code>: The name of the attribute to bind.</li> <li><code>signal</code>: The signal key or function to bind to the attribute.</li> </ul> </details>  <details> <summary>toggleAttribute(name, signal): Toggles an attribute based on a signal's truthiness</summary> Toggles the presence of an attribute on the component based on the truthiness of a signal. Adds or removes the attribute whenever the signal changes. <ul> <li><code>name</code>: The name of the attribute to toggle.</li> <li><code>signal</code>: The signal key or function to evaluate for toggling.</li> </ul> </details>  <details> <summary>toggleClass(name, signal): Toggles a class based on a signal's truthiness</summary> Adds or removes a class from the component based on the truthiness of a signal. <ul> <li><code>name</code>: The class name to toggle.</li> <li><code>signal</code>: The signal key or function to evaluate for toggling.</li> </ul> </details>  <details> <summary>setStyle(name, signal): Synchronizes a CSS style with a signal</summary> Binds a signal to a CSS style on the component, updating the style whenever the signal changes. <ul> <li><code>name</code>: The name of the CSS style property to bind.</li> <li><code>signal</code>: The signal key or function to bind to the style.</li> </ul> </details> </section> <section> <h2>6. Reactivity and Helper Functions</h2>  <details> <summary>derive(fn): Creates a derived signal from other signals</summary> Creates a signal that depends on one or more existing signals, recomputing its value whenever any of the dependencies change. <ul> <li><code>fn</code>: A function that returns the derived value, computed based on other signals.</li> </ul> </details>  <details> <summary>effect(fn): Creates a reactive effect</summary> Sets up a custom effect that runs whenever the signals used within the effect callback change. The effect can perform DOM manipulations, fetch data, or trigger other side effects. <ul> <li><code>fn</code>: The effect callback function that executes when any of its dependencies change.</li> </ul> </details>  <details> <summary>maybe(condition, callback): Conditionally runs a callback based on a signal</summary> Conditionally executes a callback function based on the truthiness of a given signal or condition. <ul> <li><code>condition</code>: A signal or function whose truthiness determines whether the callback runs.</li> <li><code>callback</code>: The function to execute if the condition is true.</li> </ul> </details>  <details> <summary>log(signal): Logs signal changes to the console</summary> Monitors the value of a signal and logs its changes to the console. Useful for debugging signal state transitions within a component. <ul> <li><code>signal</code>: The key or function for the signal to log.</li> </ul> </details> </section> </main> </body> </html>