p-elements-core 1.2.30 → 1.2.32-rc-10

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

@@ -1,63 +1,63 @@
----
-title: "customElementConfig"
-layout: "base.njk"
-description: "Documentation for @CustomElementConfig decorator"
-permalink: "/documentation/decorators/custom-element-config.html"
-eleventyNavigation:
-  parent: Decorators
-  key: CustomElementConfigDecorator
-  title: CustomElementConfig
-  order: 1
----
-
-# CustomElementConfig decorator
-
-The `@CustomElementConfig` decorator simplifies the process of defining a custom element (Web Component).
-
-## Usage
-
-Apply the `@CustomElementConfig` decorator to a class that extends `HTMLElement` or a related base class. Pass a configuration object with the `tagName` for the custom element.
-
-```typescript
-
-@CustomElementConfig({ tagName: 'my-element' })
-class MyElement extends HTMLElement {
-  connectedCallback() {
-    this.innerHTML = `<h1>Hello from My Element!</h1>`;
-  }
-}
-```
-
-This code is equivalent to:
-
-```typescript
-class MyElement extends HTMLElement {
-  connectedCallback() {
-    this.innerHTML = `<h1>Hello from My Element!</h1>`;
-  }
-}
-customElements.define('my-element', MyElement);
-```
-
-## Configuration Options
-
-- `tagName` (required): The tag name for the custom element. Must contain a hyphen (`-`).
-- `options`: An optional object passed to `customElements.define`. Currently supports:
-  - `extends`: Specifies the tag name of a built-in element to extend (e.g., `'button'` for a customized button). Requires using the `is` attribute in HTML (`<button is="my-button">`).
-
-```typescript
-// Example extending a built-in button
-@CustomElementConfig({ tagName: 'my-custom-button', options: { extends: 'button' } })
-class MyCustomButton extends HTMLButtonElement {
-  // ... custom button logic
-}
-
-// Usage in HTML:
-// <button is="my-custom-button">Click Me</button>
-```
-
-## Benefits
-
-- **Declarative:** Clearly defines the custom element's tag name alongside the class definition.
-- **Concise:** Reduces boilerplate code compared to calling `customElements.define` manually.
-- **Readability:** Improves code organization by keeping the element definition and its tag name together.
+---
+title: "customElementConfig"
+layout: "base.njk"
+description: "Documentation for @CustomElementConfig decorator"
+permalink: "/documentation/decorators/custom-element-config.html"
+eleventyNavigation:
+  parent: Decorators
+  key: CustomElementConfigDecorator
+  title: CustomElementConfig
+  order: 1
+---
+
+# CustomElementConfig decorator
+
+The `@CustomElementConfig` decorator simplifies the process of defining a custom element (Web Component).
+
+## Usage
+
+Apply the `@CustomElementConfig` decorator to a class that extends `HTMLElement` or a related base class. Pass a configuration object with the `tagName` for the custom element.
+
+```typescript
+
+@CustomElementConfig({ tagName: 'my-element' })
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `<h1>Hello from My Element!</h1>`;
+  }
+}
+```
+
+This code is equivalent to:
+
+```typescript
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `<h1>Hello from My Element!</h1>`;
+  }
+}
+customElements.define('my-element', MyElement);
+```
+
+## Configuration Options
+
+- `tagName` (required): The tag name for the custom element. Must contain a hyphen (`-`).
+- `options`: An optional object passed to `customElements.define`. Currently supports:
+  - `extends`: Specifies the tag name of a built-in element to extend (e.g., `'button'` for a customized button). Requires using the `is` attribute in HTML (`<button is="my-button">`).
+
+```typescript
+// Example extending a built-in button
+@CustomElementConfig({ tagName: 'my-custom-button', options: { extends: 'button' } })
+class MyCustomButton extends HTMLButtonElement {
+  // ... custom button logic
+}
+
+// Usage in HTML:
+// <button is="my-custom-button">Click Me</button>
+```
+
+## Benefits
+
+- **Declarative:** Clearly defines the custom element's tag name alongside the class definition.
+- **Concise:** Reduces boilerplate code compared to calling `customElements.define` manually.
+- **Readability:** Improves code organization by keeping the element definition and its tag name together.

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

@@ -1,83 +1,83 @@
----
-title: "Property decorator"
-layout: "base.njk"
-description: "Documentation for @Property decorator"
-permalink: "/documentation/decorators/property.html"
-eleventyNavigation:
-  parent: Decorators
-  key: PropertyDecorator
-  title: Property
-  order: 2
----
-
-# Property decorator
-
-The `@Property` decorator is used within custom element classes to declare reactive properties. These properties can automatically reflect their state to corresponding HTML attributes, trigger re-renders when changed, and handle type conversions.
-
-## Usage
-
-Apply the `@Property` decorator to a class field.
-
-```typescript
-@CustomElementConfig({ tagName: 'my-greeting' })
-class MyGreeting extends CustomElement {
-
-  static readonly style = `...`;
-
-  @Property({ type: 'string', reflect: true, attribute: 'name' })
-  name = 'World';
-
-  render() : VNode {
-    return <h1>Hello, ${this.name}!</h1>;
-  }
-}
-```
-
-In this example:
-- A property `name` is declared.
-- `type: 'string'` specifies the expected data type.
-- `reflect: true` means changes to the `name` property will update the `name` attribute on the `<my-greeting>` element in the DOM.
-- `attribute: 'name'` explicitly links the property to the `name` HTML attribute (defaults to the lowercase property name if omitted).
-
-## Configuration Options (`PropertyOptions`)
-
-- `type: 'string' | 'number' | 'boolean' | 'object'`: 
-  - Specifies the property's data type. 
-  - Used for automatic attribute-to-property conversion (when an attribute changes) and property-to-attribute conversion (when `reflect: true`).
-  - For `boolean`, the attribute's presence means `true`, and absence means `false`.
-  - For `object`, JSON serialization/deserialization is used for attribute reflection.
-- `reflect?: boolean`: 
-  - If `true`, changes to the property will update the corresponding attribute in the HTML.
-  - Default: `false`.
-- `attribute?: string`: 
-  - The name of the HTML attribute to associate with the property.
-  - If omitted, it defaults to the property name converted to lowercase (e.g., `myProperty` becomes `myproperty`).
-  - Set to `false` to prevent attribute association entirely.
-- `readonly?: boolean`: 
-  - If `true`, the property can only be set once. Subsequent attempts to set it will throw an error. 
-  - Useful for properties that should be initialized but not changed later.
-  - Default: `false`.
-- `converter?: AttributeConverter<any>`:
-  - An object with optional `fromAttribute` and `toAttribute` functions for custom attribute/property conversion logic.
-  - `fromAttribute(value: string | null): T`: Converts the attribute string value to the property type `T`.
-  - `toAttribute(value: T): string`: Converts the property value `T` to its string representation for the attribute.
-
-```typescript
-// Example with a custom converter for Date
-const dateConverter: AttributeConverter<Date> = {
-  fromAttribute: (value) => value ? new Date(value) : null,
-  toAttribute: (value) => value ? value.toISOString() : null
-};
-
-// ... inside class ...
-@property({ type: "object", attribute: "start-date", converter: dateConverter, reflect: true })
-startDate: Date;
-```
-
-## Reactivity
-
-When a property decorated with `@Property` changes:
-1.  If `reflect: true`, the corresponding attribute is updated.
-2.  The component's `scheduleRender()` method (if available, typically provided by a base class like `CustomElement`) is called, queueing a re-render.
-3.  The component's `updated(propertyName, oldValue, newValue)` method (if available) is called after the value has been set.
-4.  The component's `shouldUpdate(propertyName, oldValue, newValue)` method (if available) is called *before* the value is set. If it returns `false`, the property update and subsequent rendering/updated calls are skipped.
+---
+title: "Property decorator"
+layout: "base.njk"
+description: "Documentation for @Property decorator"
+permalink: "/documentation/decorators/property.html"
+eleventyNavigation:
+  parent: Decorators
+  key: PropertyDecorator
+  title: Property
+  order: 2
+---
+
+# Property decorator
+
+The `@Property` decorator is used within custom element classes to declare reactive properties. These properties can automatically reflect their state to corresponding HTML attributes, trigger re-renders when changed, and handle type conversions.
+
+## Usage
+
+Apply the `@Property` decorator to a class field.
+
+```typescript
+@CustomElementConfig({ tagName: 'my-greeting' })
+class MyGreeting extends CustomElement {
+
+  static readonly style = `...`;
+
+  @Property({ type: 'string', reflect: true, attribute: 'name' })
+  name = 'World';
+
+  render() : VNode {
+    return <h1>Hello, ${this.name}!</h1>;
+  }
+}
+```
+
+In this example:
+- A property `name` is declared.
+- `type: 'string'` specifies the expected data type.
+- `reflect: true` means changes to the `name` property will update the `name` attribute on the `<my-greeting>` element in the DOM.
+- `attribute: 'name'` explicitly links the property to the `name` HTML attribute (defaults to the lowercase property name if omitted).
+
+## Configuration Options (`PropertyOptions`)
+
+- `type: 'string' | 'number' | 'boolean' | 'object'`: 
+  - Specifies the property's data type. 
+  - Used for automatic attribute-to-property conversion (when an attribute changes) and property-to-attribute conversion (when `reflect: true`).
+  - For `boolean`, the attribute's presence means `true`, and absence means `false`.
+  - For `object`, JSON serialization/deserialization is used for attribute reflection.
+- `reflect?: boolean`: 
+  - If `true`, changes to the property will update the corresponding attribute in the HTML.
+  - Default: `false`.
+- `attribute?: string`: 
+  - The name of the HTML attribute to associate with the property.
+  - If omitted, it defaults to the property name converted to lowercase (e.g., `myProperty` becomes `myproperty`).
+  - Set to `false` to prevent attribute association entirely.
+- `readonly?: boolean`: 
+  - If `true`, the property can only be set once. Subsequent attempts to set it will throw an error. 
+  - Useful for properties that should be initialized but not changed later.
+  - Default: `false`.
+- `converter?: AttributeConverter<any>`:
+  - An object with optional `fromAttribute` and `toAttribute` functions for custom attribute/property conversion logic.
+  - `fromAttribute(value: string | null): T`: Converts the attribute string value to the property type `T`.
+  - `toAttribute(value: T): string`: Converts the property value `T` to its string representation for the attribute.
+
+```typescript
+// Example with a custom converter for Date
+const dateConverter: AttributeConverter<Date> = {
+  fromAttribute: (value) => value ? new Date(value) : null,
+  toAttribute: (value) => value ? value.toISOString() : null
+};
+
+// ... inside class ...
+@property({ type: "object", attribute: "start-date", converter: dateConverter, reflect: true })
+startDate: Date;
+```
+
+## Reactivity
+
+When a property decorated with `@Property` changes:
+1.  If `reflect: true`, the corresponding attribute is updated.
+2.  The component's `scheduleRender()` method (if available, typically provided by a base class like `CustomElement`) is called, queueing a re-render.
+3.  The component's `updated(propertyName, oldValue, newValue)` method (if available) is called after the value has been set.
+4.  The component's `shouldUpdate(propertyName, oldValue, newValue)` method (if available) is called *before* the value is set. If it returns `false`, the property update and subsequent rendering/updated calls are skipped.

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

@@ -1,66 +1,66 @@
----
-title: "Query decorator"
-layout: "base.njk"
-description: "Documentation for @Query decortator"
-permalink: "/documentation/decorators/query.html"
-eleventyNavigation:
-  parent: Decorators
-  key: QueryDecorator
-  title: Query
-  order: 4
----
-
-# Query decorator
-
-The `@Query` decorator provides a convenient way to get a reference to an element within your custom element's template (either its shadow DOM or light DOM).
-
-## Usage
-
-Apply the `@Query` decorator to a class field. Pass the CSS selector for the target element as an argument.
-
-```typescript
-
-@CustomElementConfig({ tagName: 'my-input-element' })
-class MyInputElement extends CustomElement {
-
-  static readonly style = "...";
-
-  @Query('#myInput')
-  inputElement: HTMLInputElement;
-
-  @Query('#MessageArea')
-  messageArea: HTMLDivElement;
-
-  private onChange = () => {
-    this.messageArea = this.inputElement.value;
-  }
-
-  render(): VNode {
-    return <div>
-      <input type="text" id="myInput" onchange={this.onChange} placeholder="Enter text">
-      <div id="messageArea"></div>
-    </div>;
-  }
-
-}
-```
-
-## How it Works
-
-The decorator defines a getter for the decorated property. When you access the property (e.g., `this.inputElement`):
-1.  It runs `this.shadowRoot.querySelector(selector)` by default.
-2.  If the optional second argument `useShadowRoot` is set to `false`, it runs `this.querySelector(selector)` instead, searching the element's light DOM.
-3.  It returns the first matching element or `null` if no element is found.
-
-## Parameters
-
-- `selector` (required): A string containing a CSS selector to identify the target element.
-- `useShadowRoot?: boolean`: 
-  - If `true` (the default), queries within the element's `shadowRoot`.
-  - If `false`, queries within the element's light DOM (using `this.querySelector`).
-
-## Benefits
-
-- **Declarative:** Clearly indicates which elements the component interacts with directly within the class definition.
-- **Concise:** Reduces the boilerplate of repeatedly writing `this.shadowRoot.querySelector(...)`.
-- **Readability:** Makes it easier to understand the component's structure and dependencies.
+---
+title: "Query decorator"
+layout: "base.njk"
+description: "Documentation for @Query decortator"
+permalink: "/documentation/decorators/query.html"
+eleventyNavigation:
+  parent: Decorators
+  key: QueryDecorator
+  title: Query
+  order: 4
+---
+
+# Query decorator
+
+The `@Query` decorator provides a convenient way to get a reference to an element within your custom element's template (either its shadow DOM or light DOM).
+
+## Usage
+
+Apply the `@Query` decorator to a class field. Pass the CSS selector for the target element as an argument.
+
+```typescript
+
+@CustomElementConfig({ tagName: 'my-input-element' })
+class MyInputElement extends CustomElement {
+
+  static readonly style = "...";
+
+  @Query('#myInput')
+  inputElement: HTMLInputElement;
+
+  @Query('#MessageArea')
+  messageArea: HTMLDivElement;
+
+  private onChange = () => {
+    this.messageArea = this.inputElement.value;
+  }
+
+  render(): VNode {
+    return <div>
+      <input type="text" id="myInput" onchange={this.onChange} placeholder="Enter text">
+      <div id="messageArea"></div>
+    </div>;
+  }
+
+}
+```
+
+## How it Works
+
+The decorator defines a getter for the decorated property. When you access the property (e.g., `this.inputElement`):
+1.  It runs `this.shadowRoot.querySelector(selector)` by default.
+2.  If the optional second argument `useShadowRoot` is set to `false`, it runs `this.querySelector(selector)` instead, searching the element's light DOM.
+3.  It returns the first matching element or `null` if no element is found.
+
+## Parameters
+
+- `selector` (required): A string containing a CSS selector to identify the target element.
+- `useShadowRoot?: boolean`: 
+  - If `true` (the default), queries within the element's `shadowRoot`.
+  - If `false`, queries within the element's light DOM (using `this.querySelector`).
+
+## Benefits
+
+- **Declarative:** Clearly indicates which elements the component interacts with directly within the class definition.
+- **Concise:** Reduces the boilerplate of repeatedly writing `this.shadowRoot.querySelector(...)`.
+- **Readability:** Makes it easier to understand the component's structure and dependencies.

package/docs/src/documentation/decorators/render-property-on-set.md

@@ -1,60 +1,60 @@
----
-title: "PropertyRenderOnSet decorator"
-layout: "base.njk"
-description: "documentation for @PropertyRenderOnSet decorator"
-permalink: "/documentation/decorators/property-render-on-set.html"
-eleventyNavigation:
-  parent: Decorators
-  key: PropertyRenderOnSet
-  title: PropertyRenderOnSet
-  order: 3
----
-
-# PropertyRenderOnSet decorator
-
-The `@PropertyRenderOnSet` decorator is essentially a pre-configured alias for the `@property` decorator.
-
-It simplifies the common use case of creating a property that should trigger a re-render whenever its value is set, but without needing attribute reflection or specific type handling by default.
-
-## Usage
-
-Apply the `@PropertyRenderOnSet` decorator to a class field.
-
-```typescript
-
-@CustomElementConfig({ tagName: 'my-counter' })
-class MyCounter extends CustomElement {
-
-  @PropertyRenderOnSet
-  private count = 0;
-
-  private onButtonClick = () => {
-    this.count++;
-  }
-
-  render(): VNode {
-    return <div>
-      <p>Count: {this.count}</p>
-      <button id="increment" onclick={this.onButtonClick}>Increment</button>
-    </div>;
-  }
-}
-```
-
-## How it Works
-
-`@propertyRenderOnSet` is equivalent to calling `@property({})`. This means:
-
-- It sets up a getter and setter for the property.
-- When the property is set:
-  - The component's `scheduleRender()` method (if available) is called.
-  - The component's `updated()` method (if available) is called.
-  - The component's `shouldUpdate()` method (if available) is checked beforehand.
-- It does **not** configure attribute reflection (`reflect: false` by default).
-- It does **not** enforce a specific `type` by default.
-
-## When to Use
-
-Use `@PropertyRenderOnSet` when you need internal state within your component that should trigger a re-render when it changes, but you don't need that state to be reflected as an HTML attribute or configured via an attribute.
-
-If you need attribute reflection or type conversion, use the more explicit `@Property` decorator with the appropriate options.
+---
+title: "PropertyRenderOnSet decorator"
+layout: "base.njk"
+description: "documentation for @PropertyRenderOnSet decorator"
+permalink: "/documentation/decorators/property-render-on-set.html"
+eleventyNavigation:
+  parent: Decorators
+  key: PropertyRenderOnSet
+  title: PropertyRenderOnSet
+  order: 3
+---
+
+# PropertyRenderOnSet decorator
+
+The `@PropertyRenderOnSet` decorator is essentially a pre-configured alias for the `@property` decorator.
+
+It simplifies the common use case of creating a property that should trigger a re-render whenever its value is set, but without needing attribute reflection or specific type handling by default.
+
+## Usage
+
+Apply the `@PropertyRenderOnSet` decorator to a class field.
+
+```typescript
+
+@CustomElementConfig({ tagName: 'my-counter' })
+class MyCounter extends CustomElement {
+
+  @PropertyRenderOnSet
+  private count = 0;
+
+  private onButtonClick = () => {
+    this.count++;
+  }
+
+  render(): VNode {
+    return <div>
+      <p>Count: {this.count}</p>
+      <button id="increment" onclick={this.onButtonClick}>Increment</button>
+    </div>;
+  }
+}
+```
+
+## How it Works
+
+`@propertyRenderOnSet` is equivalent to calling `@property({})`. This means:
+
+- It sets up a getter and setter for the property.
+- When the property is set:
+  - The component's `scheduleRender()` method (if available) is called.
+  - The component's `updated()` method (if available) is called.
+  - The component's `shouldUpdate()` method (if available) is checked beforehand.
+- It does **not** configure attribute reflection (`reflect: false` by default).
+- It does **not** enforce a specific `type` by default.
+
+## When to Use
+
+Use `@PropertyRenderOnSet` when you need internal state within your component that should trigger a re-render when it changes, but you don't need that state to be reflected as an HTML attribute or configured via an attribute.
+
+If you need attribute reflection or type conversion, use the more explicit `@Property` decorator with the appropriate options.

package/docs/src/documentation/decorators.md

@@ -1,9 +1,9 @@
----
-eleventyNavigation:
-  key: Decorators
-  title: Decorators
-  order: 10
----
-<script>
-  document.location.href="./custom-element-config.html";
-</script>
+---
+eleventyNavigation:
+  key: Decorators
+  title: Decorators
+  order: 10
+---
+<script>
+  document.location.href="./custom-element-config.html";
+</script>