p-elements-core 1.2.32-rc8 → 1.2.32

package/docs/src/documentation/custom-element.md

@@ -1,221 +1,221 @@
----
-title: "CustomElement class"
-layout: "base.njk"
-description: "Getting started with CustomElement Base Class"
-permalink: "/documentation/custom-element-base-class.html"
-eleventyNavigation:
-  key: CustomElementClass
-  title: CustomElement class
-  order: 3
----
-
-# CustomElement class (work in progress)
-
-The `CustomElement` base class provides a foundation for creating web components within the p-elements-core framework. It simplifies common tasks like rendering, managing properties, handling lifecycle events, and applying styles.
-
-## Getting Started
-
-To create a new custom element, extend the `CustomElement` class and use the `@customElementConfig` decorator to define its tag name.
-
-```typescript
-@CustomElementConfig({ tagName: 'my-element' })
-export class MyElement extends CustomElement {
-
-  static readonly style = `
-  :host{
-    color: green;
-  }
-  `;
-
-  // https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#delegatesfocus
-  static readonly delegatesFocus = true; // optional if true, the shadowroot is created with param delegatesFocus
-
-  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals
-  static readonly formAssociated = true; // optional Allows a custom element to participate in HTML forms.
-
-  static readonly projectorMode = "replace"; // Optional could be "append" | "merge" | "replace"
-
-  @property({ type: 'string', reflect: true, attribute: 'message' })
-  message: string = 'Hello';
-
-  // Initialize component state or perform setup (optional)
-  init() {
-    console.log('MyElement initialized');
-  }
-
-  // Define the component's template
-  render() {
-    return <div>{this.message}</div>
-  }
-
-  // Called after the component is connected to the DOM (optional)
-  connectedCallback() {
-    super.connectedCallback(); // Call super if overriding
-    console.log('MyElement connected');
-  }
-
-  // Called after the component is disconnected from the DOM (optional)
-  disconnectedCallback() {
-    super.disconnectedCallback(); // Call super if overriding
-    console.log('MyElement disconnected');
-  }
-
-  // Called when an observed attribute changes (optional)
-  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
-    super.attributeChangedCallback(name, oldValue, newValue); // Call super if overriding
-    console.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
-  }
-
-  // Called before rendering starts (optional)
-  renderStart(isFirstRender: boolean) {
-    console.log('Render starting...', isFirstRender ? '(first time)' : '');
-  }
-
-  // Called after rendering finishes (optional)
-  renderDone(isFirstRender: boolean) {
-    console.log('Render done.', isFirstRender ? '(first time)' : '');
-  }
-
-  shouldUpdate(property: string, oldValue: any, newValue: any) {
-    // Called before a property update, property is not updated if returns false (optional)
-    console.info("shouldUpdate", { property, oldValue, newValue });
-    return true;
-  }
-  // Called after a property update triggers a re-render (optional)
-  updated(propertyName: string, oldValue: any, newValue: any) {
-    console.log(`Property ${propertyName} updated from ${oldValue} to ${newValue}`);
-  }
-}
-```
-
-## Core Concepts
-
-### 1. Defining the Element (`@CustomElementConfig`)
-
-Use the `@CustomElementConfig` decorator on your class to register it with the browser's `CustomElementRegistry`.
-
-
-### 2. Rendering (`render()` method)
-
-The `render()` method is **required**. It should return a virtual DOM representation of your element's content, 
-using TSX. `CustomElement` uses Maquette's projector internally to efficiently update the DOM.
-
-```typescript
-
-// ... inside your class
-render() {
-  return <div>Hello world</div>;
-}
-```
-
-The rendering engine automatically schedules updates when reactive properties change. You can manually trigger a render using `this.scheduleRender()` or force an immediate synchronous render with `this.renderNow()`.
-
-### 3. Reactive Properties (`@Property` decorator)
-
-Declare properties that should trigger re-renders when changed using the `@property` decorator.
-
-```typescript
-// ... inside your class
-@property({
-  type: 'string',      // Data type ('string', 'number', 'boolean', 'object')
-  reflect: true,       // Reflect property value to an attribute?
-  attribute: 'my-attr', // Custom attribute name (defaults to property name)
-  readonly: false,     // Make the property read-only after first set?
-  converter: {         // Optional: Custom attribute-to-property conversion
-    fromAttribute: (value) => value ? value.toUpperCase() : undefined,
-    toAttribute: (value) => value ? value.toLowerCase() : undefined
-  }
-})
-myProp: string = 'initial value';
-
-@property({ type: 'boolean', reflect: true })
-disabled: boolean = false;
-
-@property({ type: 'number' })
-count: number = 0;
-
-@property({ type: 'object' })
-data: { id: number, name: string };
-```
-
-- **`type`**: Helps with automatic attribute-to-property conversion (especially for `boolean` and `number`).
-- **`reflect`**: If `true`, the property's value is automatically reflected to the corresponding HTML attribute.
-- **`attribute`**: Specifies the HTML attribute name to link with the property. If omitted, it defaults to the property name (e.g., `myProp` becomes `myprop`). For  - **`readonly`**: If `true`, the property can only be set once. Subsequent attempts will throw an error.
-- **`converter`**: Provides custom logic for converting between attribute strings and property values.
-
-When a property decorated with `@Property` changes, `scheduleRender()` is called automatically. If the property has `reflect: true` and an associated `attribute`, the attribute value is updated accordingly.
-
-### 4. Lifecycle Methods
-
-`CustomElement` provides hooks into the standard custom element lifecycle and its own rendering cycle:
-
-- **`constructor()`**: Called when the element instance is created. Basic initialization happens here.
-- **`init()`**: An optional custom initialization method called after the base class constructor logic finishes but before the first render. Good place for setting up initial state or listeners that don't depend on the DOM.
-- **`connectedCallback()`**: Called when the element is inserted into the DOM. Use this for DOM-dependent setup. Remember to call `super.connectedCallback()` if you override it.
-- **`disconnectedCallback()`**: Called when the element is removed from the DOM. Use for cleanup. Remember to call `super.disconnectedCallback()`.
-- **`attributeChangedCallback(name, oldValue, newValue)`**: Called when an attribute listed in the static `observedAttributes` getter changes. `CustomElement` automatically populates `observedAttributes` based on `@property` decorators with an `attribute` defined and handles updating the corresponding property. You usually only need to override this for attributes *not* managed by `@property`. Call `super.attributeChangedCallback()` to ensure property updates still occur.
-- **`renderStart(isFirstRender: boolean)`**: Called just before the Maquette projector starts a render cycle. `isFirstRender` is true only for the very first render.
-- **`renderDone(isFirstRender: boolean)`**: Called just after the Maquette projector finishes a render cycle and updates the DOM. `isFirstRender` is true only for the very first render.
-- **`shouldUpdate(propertyName, oldValue, newValue)`** Called before update a reactive property, if the method returns true the property will be updated.  
-- **`updated(propertyName, oldValue, newValue)`**: Called *after* a reactive property has been updated and the subsequent render cycle (if any) has completed.
-
-### 5. Styling
-
-There are several ways to style your `CustomElement`:
-
-- **Shadow DOM with Static `style` Property**: The recommended approach for encapsulated styles. Define a static `style` property containing your CSS string. `CustomElement` will automatically create a shadow root (if not present) and attach the styles.
-
-  ```typescript
-  import { css } from 'p-elements-core/helpers/css'; // Optional helper
-
-  @customElementConfig({ tagName: 'styled-element' })
-  export class StyledElement extends CustomElement {
-    static readonly style = css`
-      :host {
-        display: block;
-        border: 1px solid blue;
-        padding: 1rem;
-      }
-      p {
-        color: blue;
-      }
-    `;
-
-    render() {
-      return <div><p>Hello world</p></div>;
-    }
-  }
-  ```
-  This method uses adopted stylesheets if supported by the browser, falling back to `<link>` elements otherwise. It also includes a polyfill for the abandoned `@apply` CSS proposal using CSS variables. This polyfill is just for backwards compatibility.
-
-- **Shadow DOM with `<template>`**: Use `this.templateFromString(htmlString)` in your constructor or `init` method. The method parses the string, extracts and applies the `<style>` tag content to the shadow root, and returns the template content `DocumentFragment`.
-
-### 6. Controllers
-
-Controllers (`ICustomElementController`) are separate classes that can hook into the element's lifecycle to manage specific behaviors (like handling focus, state management, etc.).
-
-```typescript
-// In your element class
-import { MyController } from './my-controller';
-
-// ... inside your class
-#myController = new MyController(this); // Pass host element
-
-constructor() {
-  super();
-  this.addController(this.#myController);
-  // ...
-}
-```
-
-The `CustomElement` will automatically call the controller's corresponding lifecycle methods (`init`, `connected`, `disconnected`, `hostRenderStart`, `hostRenderDone`). 
-
-### 7. Form Association
-
-To make your custom element participate in forms (like a native `<input>`), add a static `formAssociated = true` property and use `this.internals` (ElementInternals API).
-
-### 8. Advanced Topics
-
-- **Projector Mode**: Control how Maquette renders content relative to the host element (or shadow root container) using the static `projectorMode` property (`'append'`, `'merge'`, or `'replace'`). Defaults to `'append'` unless a static `style` is provided (then defaults to `'replace'` within the shadow root).
-- **Focus Delegation**: Set static `delegatesFocus = true` to forward focus into the shadow root. Requires a shadow root.
-- **`ElementInternals`**: Access via `this.internals` when `static formAssociated = true`. Used for form participation, accessibility roles/states, etc.
+---
+title: "CustomElement class"
+layout: "base.njk"
+description: "Getting started with CustomElement Base Class"
+permalink: "/documentation/custom-element-base-class.html"
+eleventyNavigation:
+  key: CustomElementClass
+  title: CustomElement class
+  order: 3
+---
+
+# CustomElement class (work in progress)
+
+The `CustomElement` base class provides a foundation for creating web components within the p-elements-core framework. It simplifies common tasks like rendering, managing properties, handling lifecycle events, and applying styles.
+
+## Getting Started
+
+To create a new custom element, extend the `CustomElement` class and use the `@customElementConfig` decorator to define its tag name.
+
+```typescript
+@CustomElementConfig({ tagName: 'my-element' })
+export class MyElement extends CustomElement {
+
+  static readonly style = `
+  :host{
+    color: green;
+  }
+  `;
+
+  // https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#delegatesfocus
+  static readonly delegatesFocus = true; // optional if true, the shadowroot is created with param delegatesFocus
+
+  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals
+  static readonly formAssociated = true; // optional Allows a custom element to participate in HTML forms.
+
+  static readonly projectorMode = "replace"; // Optional could be "append" | "merge" | "replace"
+
+  @property({ type: 'string', reflect: true, attribute: 'message' })
+  message: string = 'Hello';
+
+  // Initialize component state or perform setup (optional)
+  init() {
+    console.log('MyElement initialized');
+  }
+
+  // Define the component's template
+  render() {
+    return <div>{this.message}</div>
+  }
+
+  // Called after the component is connected to the DOM (optional)
+  connectedCallback() {
+    super.connectedCallback(); // Call super if overriding
+    console.log('MyElement connected');
+  }
+
+  // Called after the component is disconnected from the DOM (optional)
+  disconnectedCallback() {
+    super.disconnectedCallback(); // Call super if overriding
+    console.log('MyElement disconnected');
+  }
+
+  // Called when an observed attribute changes (optional)
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
+    super.attributeChangedCallback(name, oldValue, newValue); // Call super if overriding
+    console.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
+  }
+
+  // Called before rendering starts (optional)
+  renderStart(isFirstRender: boolean) {
+    console.log('Render starting...', isFirstRender ? '(first time)' : '');
+  }
+
+  // Called after rendering finishes (optional)
+  renderDone(isFirstRender: boolean) {
+    console.log('Render done.', isFirstRender ? '(first time)' : '');
+  }
+
+  shouldUpdate(property: string, oldValue: any, newValue: any) {
+    // Called before a property update, property is not updated if returns false (optional)
+    console.info("shouldUpdate", { property, oldValue, newValue });
+    return true;
+  }
+  // Called after a property update triggers a re-render (optional)
+  updated(propertyName: string, oldValue: any, newValue: any) {
+    console.log(`Property ${propertyName} updated from ${oldValue} to ${newValue}`);
+  }
+}
+```
+
+## Core Concepts
+
+### 1. Defining the Element (`@CustomElementConfig`)
+
+Use the `@CustomElementConfig` decorator on your class to register it with the browser's `CustomElementRegistry`.
+
+
+### 2. Rendering (`render()` method)
+
+The `render()` method is **required**. It should return a virtual DOM representation of your element's content, 
+using TSX. `CustomElement` uses Maquette's projector internally to efficiently update the DOM.
+
+```typescript
+
+// ... inside your class
+render() {
+  return <div>Hello world</div>;
+}
+```
+
+The rendering engine automatically schedules updates when reactive properties change. You can manually trigger a render using `this.scheduleRender()` or force an immediate synchronous render with `this.renderNow()`.
+
+### 3. Reactive Properties (`@Property` decorator)
+
+Declare properties that should trigger re-renders when changed using the `@property` decorator.
+
+```typescript
+// ... inside your class
+@property({
+  type: 'string',      // Data type ('string', 'number', 'boolean', 'object')
+  reflect: true,       // Reflect property value to an attribute?
+  attribute: 'my-attr', // Custom attribute name (defaults to property name)
+  readonly: false,     // Make the property read-only after first set?
+  converter: {         // Optional: Custom attribute-to-property conversion
+    fromAttribute: (value) => value ? value.toUpperCase() : undefined,
+    toAttribute: (value) => value ? value.toLowerCase() : undefined
+  }
+})
+myProp: string = 'initial value';
+
+@property({ type: 'boolean', reflect: true })
+disabled: boolean = false;
+
+@property({ type: 'number' })
+count: number = 0;
+
+@property({ type: 'object' })
+data: { id: number, name: string };
+```
+
+- **`type`**: Helps with automatic attribute-to-property conversion (especially for `boolean` and `number`).
+- **`reflect`**: If `true`, the property's value is automatically reflected to the corresponding HTML attribute.
+- **`attribute`**: Specifies the HTML attribute name to link with the property. If omitted, it defaults to the property name (e.g., `myProp` becomes `myprop`). For  - **`readonly`**: If `true`, the property can only be set once. Subsequent attempts will throw an error.
+- **`converter`**: Provides custom logic for converting between attribute strings and property values.
+
+When a property decorated with `@Property` changes, `scheduleRender()` is called automatically. If the property has `reflect: true` and an associated `attribute`, the attribute value is updated accordingly.
+
+### 4. Lifecycle Methods
+
+`CustomElement` provides hooks into the standard custom element lifecycle and its own rendering cycle:
+
+- **`constructor()`**: Called when the element instance is created. Basic initialization happens here.
+- **`init()`**: An optional custom initialization method called after the base class constructor logic finishes but before the first render. Good place for setting up initial state or listeners that don't depend on the DOM.
+- **`connectedCallback()`**: Called when the element is inserted into the DOM. Use this for DOM-dependent setup. Remember to call `super.connectedCallback()` if you override it.
+- **`disconnectedCallback()`**: Called when the element is removed from the DOM. Use for cleanup. Remember to call `super.disconnectedCallback()`.
+- **`attributeChangedCallback(name, oldValue, newValue)`**: Called when an attribute listed in the static `observedAttributes` getter changes. `CustomElement` automatically populates `observedAttributes` based on `@property` decorators with an `attribute` defined and handles updating the corresponding property. You usually only need to override this for attributes *not* managed by `@property`. Call `super.attributeChangedCallback()` to ensure property updates still occur.
+- **`renderStart(isFirstRender: boolean)`**: Called just before the Maquette projector starts a render cycle. `isFirstRender` is true only for the very first render.
+- **`renderDone(isFirstRender: boolean)`**: Called just after the Maquette projector finishes a render cycle and updates the DOM. `isFirstRender` is true only for the very first render.
+- **`shouldUpdate(propertyName, oldValue, newValue)`** Called before update a reactive property, if the method returns true the property will be updated.  
+- **`updated(propertyName, oldValue, newValue)`**: Called *after* a reactive property has been updated and the subsequent render cycle (if any) has completed.
+
+### 5. Styling
+
+There are several ways to style your `CustomElement`:
+
+- **Shadow DOM with Static `style` Property**: The recommended approach for encapsulated styles. Define a static `style` property containing your CSS string. `CustomElement` will automatically create a shadow root (if not present) and attach the styles.
+
+  ```typescript
+  import { css } from 'p-elements-core/helpers/css'; // Optional helper
+
+  @customElementConfig({ tagName: 'styled-element' })
+  export class StyledElement extends CustomElement {
+    static readonly style = css`
+      :host {
+        display: block;
+        border: 1px solid blue;
+        padding: 1rem;
+      }
+      p {
+        color: blue;
+      }
+    `;
+
+    render() {
+      return <div><p>Hello world</p></div>;
+    }
+  }
+  ```
+  This method uses adopted stylesheets if supported by the browser, falling back to `<link>` elements otherwise. It also includes a polyfill for the abandoned `@apply` CSS proposal using CSS variables. This polyfill is just for backwards compatibility.
+
+- **Shadow DOM with `<template>`**: Use `this.templateFromString(htmlString)` in your constructor or `init` method. The method parses the string, extracts and applies the `<style>` tag content to the shadow root, and returns the template content `DocumentFragment`.
+
+### 6. Controllers
+
+Controllers (`ICustomElementController`) are separate classes that can hook into the element's lifecycle to manage specific behaviors (like handling focus, state management, etc.).
+
+```typescript
+// In your element class
+import { MyController } from './my-controller';
+
+// ... inside your class
+#myController = new MyController(this); // Pass host element
+
+constructor() {
+  super();
+  this.addController(this.#myController);
+  // ...
+}
+```
+
+The `CustomElement` will automatically call the controller's corresponding lifecycle methods (`init`, `connected`, `disconnected`, `hostRenderStart`, `hostRenderDone`). 
+
+### 7. Form Association
+
+To make your custom element participate in forms (like a native `<input>`), add a static `formAssociated = true` property and use `this.internals` (ElementInternals API).
+
+### 8. Advanced Topics
+
+- **Projector Mode**: Control how Maquette renders content relative to the host element (or shadow root container) using the static `projectorMode` property (`'append'`, `'merge'`, or `'replace'`). Defaults to `'append'` unless a static `style` is provided (then defaults to `'replace'` within the shadow root).
+- **Focus Delegation**: Set static `delegatesFocus = true` to forward focus into the shadow root. Requires a shadow root.
+- **`ElementInternals`**: Access via `this.internals` when `static formAssociated = true`. Used for form participation, accessibility roles/states, etc.

package/docs/src/documentation/decorators/bind.md

@@ -1,71 +1,71 @@
----
-title: "Bind decorator"
-layout: "base.njk"
-description: "Documentation for @Bind decorator"
-permalink: "/documentation/decorators/bind.html"
-eleventyNavigation:
-  parent: Decorators
-  key: DecoratorsBuery
-  title: Bind
-  order: 5
----
-
-
-# Bind decorator
-
-**Note:** This decorator is deprecated. It's recommended to use arrow function expressions instead for binding `this`.
-
-The `@Bind` decorator automatically binds a class method to the instance of the class. This ensures that `this` inside the method always refers to the class instance, even when the method is passed as a callback or event handler.
-
-## Usage
-
-Apply the `@Bind` decorator directly above the method definition.
-
-```typescript
-class MyComponent extends HTMLElement {
-  message = "Hello!";
-
-  @Bind
-  handleClick() {
-    console.log(this.message); // 'this' correctly refers to the MyComponent instance
-  }
-
-  connectedCallback() {
-    this.addEventListener('click', this.handleClick);
-  }
-
-  disconnectedCallback() {
-    this.removeEventListener('click', this.handleClick);
-  }
-}
-
-customElements.define('my-component', MyComponent);
-```
-
-## Why use it? (Deprecated)
-
-In JavaScript, the value of `this` can change depending on how a function is called. When passing a method as a callback (like in `addEventListener`), `this` might not refer to the class instance, leading to errors. `@Bind` solves this by ensuring the method is always bound to the instance.
-
-## Alternative (Recommended)
-
-Use arrow function expressions for class methods that need to be bound:
-
-```typescript
-class MyComponent extends HTMLElement {
-  message = "Hello!";
-
-  handleClick = () => {
-    console.log(this.message); // 'this' correctly refers to the MyComponent instance
-  }
-
-  connectedCallback() {
-    this.addEventListener('click', this.handleClick);
-  }
-
-  disconnectedCallback() {
-    this.removeEventListener('click', this.handleClick);
-  }
-}
-
-customElements.define('my-component', MyComponent);
-```
+---
+title: "Bind decorator"
+layout: "base.njk"
+description: "Documentation for @Bind decorator"
+permalink: "/documentation/decorators/bind.html"
+eleventyNavigation:
+  parent: Decorators
+  key: DecoratorsBuery
+  title: Bind
+  order: 5
+---
+
+
+# Bind decorator
+
+**Note:** This decorator is deprecated. It's recommended to use arrow function expressions instead for binding `this`.
+
+The `@Bind` decorator automatically binds a class method to the instance of the class. This ensures that `this` inside the method always refers to the class instance, even when the method is passed as a callback or event handler.
+
+## Usage
+
+Apply the `@Bind` decorator directly above the method definition.
+
+```typescript
+class MyComponent extends HTMLElement {
+  message = "Hello!";
+
+  @Bind
+  handleClick() {
+    console.log(this.message); // 'this' correctly refers to the MyComponent instance
+  }
+
+  connectedCallback() {
+    this.addEventListener('click', this.handleClick);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('click', this.handleClick);
+  }
+}
+
+customElements.define('my-component', MyComponent);
+```
+
+## Why use it? (Deprecated)
+
+In JavaScript, the value of `this` can change depending on how a function is called. When passing a method as a callback (like in `addEventListener`), `this` might not refer to the class instance, leading to errors. `@Bind` solves this by ensuring the method is always bound to the instance.
+
+## Alternative (Recommended)
+
+Use arrow function expressions for class methods that need to be bound:
+
+```typescript
+class MyComponent extends HTMLElement {
+  message = "Hello!";
+
+  handleClick = () => {
+    console.log(this.message); // 'this' correctly refers to the MyComponent instance
+  }
+
+  connectedCallback() {
+    this.addEventListener('click', this.handleClick);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('click', this.handleClick);
+  }
+}
+
+customElements.define('my-component', MyComponent);
+```