Introduction

a.js is a lightweight and versatile JavaScript Flexwork/library designed for building reactive and dynamic web components. It extends the power of native web components by introducing custom tags (<a-script>, <a-closure>, and <a-tagDef>) that simplify complex operations such as state management, reactivity, and scoped behavior. These custom tags integrate seamlessly with modern JavaScript, allowing developers to create dynamic user interfaces with ease.

This documentation is targeted at developers familiar with JavaScript. Knowledge about web components and proxies is useful to understand what's going one behind the scene. If you are unfamiliar with these concepts, refer to the following resources for a brief primer:

• Web Components: MDN Web Components Guide
• JavaScript Proxies: MDN Proxy Documentation

Key Highlights

• Enhanced web components for rapid UI development.
• Reactive variables managed through JavaScript proxies.
• Modular and reusable code through <a-tagDef>.
• Allows redefining web components already declared with a.js.
• Seamless integration with HTML and JavaScript ecosystems.

Overview of Features

Custom HTML Tags

a.js introduces three primary custom tags to enhance web development:

1. <a-script>
   • A custom replacement for the <script> tag with additional functionality, including scoped execution and integration with a.js features.
2. <a-closure>
   • Encapsulates JavaScript code in a closure for isolated execution, preventing global namespace pollution.
3. <a-tagDef>
   • Defines reusable custom components that can be dynamically instantiated in the DOM and re-defined when necessary.

Special Variables and Behaviors

• currentScript and currentElement:
  • Provide references to the active <script> or target element within a.js tags, streamlining access to DOM elements.
• Enhanced Reactivity:
  • Watched variables defined within <let> blocks use JavaScript proxies for fine-grained reactivity, enabling automatic updates to UI elements.
  • Non-watched variables defined within <let> blocks allow you to maintain state inside a component or between several of them without triggering reactivity.

Modular Imports

• <import> tag:
  • Dynamically import JavaScript, CSS, or HTML fragments.
  • Includes recursive resolution of imports within <a-xxx> tags.

Advanced Features

• Scoped Variables: Manage variables at global, namespace, or local levels with fine control over their visibility and lifecycle.
• Reactive Loops: Use <forEachOf> tags to create dynamically reactive lists.
• Dynamic Keyed Elements: Optimize updates for elements inside reactive loops by using unique keys.
• Custom Event Handling: Automatically attach reactive event listeners to DOM elements created with a.js.