Datastar Components v1.0.0-alpha

[youngvernon]

Stability, Consistency, and Enhanced Developer Experience

We're excited to announce the v1.0.0-alpha release of the Datastar Components plugin! This major release solidifies the plugin's foundation, bringing greater consistency, enhanced lifecycle management, and improved debugging capabilities, all while maintaining its core philosophy of HTML-first Web Component development with seamless DatastarJS reactivity.

Building upon the strong foundation of the initial pre-release (v0.1.0-alpha), v1.0.0-alpha introduces key refinements and new features that make building reusable and reactive components even more intuitive and robust.

---

What's New and Changed in v1.0.0-alpha:

• Refined Attribute Naming for Consistency

  • To improve clarity and consistency, several key attributes have been renamed. The v0.1.0-alpha attributes such as data-prop-* for reactive properties, data-load-if for conditional loading, and data-component-error-src for fallback UI have been standardized.
  • data-prop-* is now data-component-prop-*: This change ensures that all component-related attributes are consistently prefixed with data-component-, making them easier to identify and manage within your HTML.
  • data-load-if is now data-component-load-if: The attribute for conditionally loading components has also adopted the data-component- prefix for better organization.
  • data-component-error-src is now data-component-fallback: This attribute, used to specify a URL for fallback content when a component fails to load or script errors occur, has been renamed for clearer intent.

• Enhanced Lifecycle Management with Declarative Control

  • Beyond the existing contentReadyCallback and registerCleanup for disconnectedCallback, v1.0.0-alpha introduces declarative attributes for more explicit lifecycle event handling:
    • data-on:component-connected: Allows you to define Datastar actions or expressions to be executed when the component is connected to the DOM.
    • data-on:component-disconnected: Enables actions or expressions to run when the component is removed from the DOM, ideal for cleanup or logging.
  • The registerCleanup method for imperative cleanup on disconnectedCallback is still fully supported and encouraged for preventing memory leaks.
  • adoptedCallback integration has been solidified, ensuring Datastar reactivity is re-initialized when a custom element is adopted into a new document.

• Comprehensive Error Reporting and Debugging

  • v1.0.0-alpha significantly enhances error handling by dispatching dedicated custom events for various component lifecycle issues, enabling centralized monitoring and more robust recovery strategies:
    • component-load-error: Fired when a component's source HTML fails to load.
    • component-script-error: Fired if an error occurs during the execution of JavaScript within the component.
    • component-fallback-rendered: Indicates when a fallback UI has been successfully rendered due to a component failure.
  • These events provide detailed detail objects, including the component's tag name, source URL, and the original error, facilitating easier debugging and custom error displays.

• Improved JavaScript Execution Model

  • The plugin now more explicitly handles all types of <script> tags (module, classic, external, inline) sequentially and reliably within your component's scope.
  • Top-level exported functions within module scripts are automatically registered as Datastar actions, allowing for seamless integration of imperative logic with declarative calls from your HTML.

• Streamlined Documentation and Storybook Integration

  • The README.v1.0.0.md (now reflecting v1.0.0-alpha features) provides more comprehensive and detailed documentation, including clearer examples and explanations for all features.
  • A dedicated LitElement wrapper (datastar-components-storyboard-wrapper.v1.0.0.js) is provided to simplify creating Storybook stories for your Datastar Components. This wrapper dynamically generates data-component-src, data-component-prop-*, and data-signals attributes based on LitElement properties, streamlining your component documentation workflow. It also includes data-on:connected and data-on:disconnected event handlers for mirroring lifecycle events in Storybook.

• Internal Stability and Performance Enhancements

  • Under the hood, v1.0.0-alpha includes various code refinements, improved error logging, and minor performance tweaks to ensure a more stable and efficient experience. This includes careful handling of Constructable Stylesheets and DOM mutation observation.

---

Why Upgrade to v1.0.0-alpha?

This release focuses on hardening the plugin's API, enhancing developer ergonomics, and providing more robust tools for debugging and error handling. The consistent attribute naming makes the API more predictable, while the extended lifecycle and error reporting give you greater control and visibility into your components' behavior. If you're building complex, production-ready Web Components with Datastar, v1.0.0-alpha is the stable and powerful foundation you need.

---

Get Started with v1.0.0-alpha!
Explore the updated documentation for detailed usage instructions and examples.

• [Datastar Components GitHub Repository](https://www.google.com/search?q=https://github.com/aereaco/datastar-components)
• [Datastar Components Documentation](https://www.google.com/search?q=https://github.com/aereaco/datastar-components/blob/main/README.md)**Datastar Components Plugin - v1.0.0-alpha Release: Stability, Consistency, and Enhanced Developer Experience**

We're excited to announce the v1.0.0-alpha release of the Datastar Components plugin! This major release solidifies the plugin's foundation, bringing greater consistency, enhanced lifecycle management, and improved debugging capabilities, all while maintaining its core philosophy of HTML-first Web Component development with seamless DatastarJS reactivity.

Building upon the strong foundation of the initial pre-release (v0.1.0-alpha), v1.0.0-alpha introduces key refinements and new features that make building reusable and reactive components even more intuitive and robust.

---

What's New and Changed in v1.0.0-alpha:

• Refined Attribute Naming for Consistency

  • To improve clarity and consistency, several key attributes have been renamed. The v0.1.0-alpha attributes such as data-prop-* for reactive properties, data-load-if for conditional loading, and data-component-error-src for fallback UI have been standardized.
  • data-prop-* is now data-component-prop-*: This change ensures that all component-related attributes are consistently prefixed with data-component-, making them easier to identify and manage within your HTML.
  • data-load-if is now data-component-load-if: The attribute for conditionally loading components has also adopted the data-component- prefix for better organization.
  • data-component-error-src is now data-component-fallback: This attribute, used to specify a URL for fallback content when a component fails to load or script errors occur, has been renamed for clearer intent.

• Enhanced Lifecycle Management with Declarative Control

  • Beyond the existing contentReadyCallback and registerCleanup for disconnectedCallback, v1.0.0-alpha introduces declarative attributes for more explicit lifecycle event handling:
    • data-on:component-connected: Allows you to define Datastar actions or expressions to be executed when the component is connected to the DOM.
    • data-on:component-disconnected: Enables actions or expressions to run when the component is removed from the DOM, ideal for cleanup or logging.
  • The registerCleanup method for imperative cleanup on disconnectedCallback is still fully supported and encouraged for preventing memory leaks.
  • adoptedCallback integration has been solidified, ensuring Datastar reactivity is re-initialized when a custom element is adopted into a new document.

• Comprehensive Error Reporting and Debugging

  • v1.0.0-alpha significantly enhances error handling by dispatching dedicated custom events for various component lifecycle issues, enabling centralized monitoring and more robust recovery strategies:
    • component-load-error: Fired when a component's source HTML fails to load.
    • component-script-error: Fired if an error occurs during the execution of JavaScript within the component.
    • component-fallback-rendered: Indicates when a fallback UI has been successfully rendered due to a component failure.
  • These events provide detailed detail objects, including the component's tag name, source URL, and the original error, facilitating easier debugging and custom error displays.

• Improved JavaScript Execution Model

  • The plugin now more explicitly handles all types of <script> tags (module, classic, external, inline) sequentially and reliably within your component's scope.
  • Top-level exported functions within module scripts are automatically registered as Datastar actions, allowing for seamless integration of imperative logic with declarative calls from your HTML.

• Streamlined Documentation and Storybook Integration

  • The README.v1.0.0.md (now reflecting v1.0.0-alpha features) provides more comprehensive and detailed documentation, including clearer examples and explanations for all features.
  • A dedicated LitElement wrapper (datastar-components-storyboard-wrapper.v1.0.0.js) is provided to simplify creating Storybook stories for your Datastar Components. This wrapper dynamically generates data-component-src, data-component-prop-*, and data-signals attributes based on LitElement properties, streamlining your component documentation workflow. It also includes data-on:connected and data-on:disconnected event handlers for mirroring lifecycle events in Storybook.

• Internal Stability and Performance Enhancements

  • Under the hood, v1.0.0-alpha includes various code refinements, improved error logging, and minor performance tweaks to ensure a more stable and efficient experience. This includes careful handling of Constructable Stylesheets and DOM mutation observation.

---

Why Upgrade to v1.0.0-alpha?

This release focuses on hardening the plugin's API, enhancing developer ergonomics, and providing more robust tools for debugging and error handling. The consistent attribute naming makes the API more predictable, while the extended lifecycle and error reporting give you greater control and visibility into your components' behavior. If you're building complex, production-ready Web Components with Datastar, v1.0.0-alpha is the stable and powerful foundation you need.

---

Get Started with v1.0.0-alpha!
Explore the updated documentation for detailed usage instructions and examples.

• [Datastar Components GitHub Repository](https://github.com/aereaco/datastar-components)

---

This discussion was created from the release Datastar Components v1.0.0-alpha.